연락처·거래·여정 API

이 엔드포인트로 내 코드, Zapier, n8n이 계정에서 작업할 수 있습니다. 연락처 추가, 거래 생성과 이동, 여정에 연락처 등록, 그리고 이런 호출에 필요한 ID 조회가 가능합니다. 발송 API와 같은 API 키를 사용합니다.

Authorization: Bearer mia_live_...

엔드포인트 묶음마다 키당 분당 60개 요청까지 허용합니다. 넘으면 429가 반환됩니다. 오류는 4xx 상태와 함께 {"error": "…"}로 반환됩니다. 모든 응답 형식을 포함한 전체 규격은 OpenAPI 명세에 있습니다.

연락처

만들기 또는 업데이트

POST /api/v1/contacts는 연락처 목록에 주소를 추가하고, 이미 있으면 업데이트합니다.

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

새 연락처면 201, 업데이트면 200과 함께 저장된 연락처를 반환합니다. 한 번에 최대 500명을 보내려면 {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}을 사용하세요. 이 경우 개수를 반환합니다.

모든 주소는 저장할 때 확인됩니다. API는 동의 답을 기록하지 않으므로, 이 연락처들은 이전처럼 발송 대상이 됩니다. 연락처 한 명이 플랜의 연락처 한도를 넘게 하면 409가 반환됩니다.

찾기

GET /api/v1/[email protected]은 그 주소의 연락처를 모든 목록에서 최신순으로 반환합니다. &listId=를 붙이면 한 목록에서만 찾습니다. 조회는 대시보드에서 연락처를 볼 때처럼 계정의 개인정보 접근 로그에 기록됩니다.

목록

GET /api/v1/lists는 각 연락처 목록의 id, name, fields, rowCount를 반환합니다. 연락처 데이터는 포함하지 않습니다.

거래

만들기

POST /api/v1/deals:

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 1200000,
  "currency": "KRW"
}

연락처는 email로, 또는 listId와 rowId로 지정합니다. 이메일만 있으면 그 주소가 있는 목록 중 가장 최근에 업데이트된 목록에 거래가 만들어집니다. pipelineId와 stageId가 없으면 기본 파이프라인의 첫 번째 진행 중 단계에 들어갑니다. currency의 기본값은 USD입니다.

Idempotency-Key 헤더(예: 주문 번호)를 보내면 재시도를 안전하게 할 수 있습니다. 같은 키로 반복하면 두 번째 거래를 만들지 않고 "created": false와 함께 200을 반환합니다.

업데이트 또는 이동

PATCH /api/v1/deals/{id}는 title, value, currency, stageId를 받습니다. 성사나 실패 단계로 옮기면 거래가 종료됩니다. 본문 전체를 먼저 검증하므로, 알 수 없는 단계를 지정하면 아무것도 바뀌지 않습니다. 이동하면 보드에서 옮길 때와 마찬가지로 여정 트리거 거래 단계 변경과 웹훅 deal.stage_changed가 발생합니다.

파이프라인

GET /api/v1/pipelines는 기본 파이프라인을 먼저 두고, 각 파이프라인과 단계(id, name, kind)를 반환합니다. 거래를 옮길 stageId를 찾을 때 사용하세요.

여정

GET /api/v1/journeys는 여정의 ID, 이름, 트리거, 켜짐 여부를 나열합니다. ?trigger=api를 붙이면 내 코드가 연락처를 등록할 수 있는 여정만 반환합니다.

POST /api/v1/journeys/{id}/trigger에 {"email": "…", "listId": "…"}를 보내면 트리거가 API 호출인 여정에 연락처를 등록합니다. 여정을 참고하세요.

샘플 이벤트

GET /api/v1/events/sample?type=deal.stage_changed는 그 유형의 웹훅 봉투 샘플을 {"events": [ … ]}로 반환합니다. type을 빼면 모든 유형의 샘플을 하나씩 반환합니다. 자동화 도구는 실제 이벤트가 오기 전에 필드를 보여 주는 데 이것을 씁니다.

웹훅

GET, POST /api/v1/webhooks와 DELETE /api/v1/webhooks/{id}로 이벤트 구독을 관리합니다. 웹훅과 이벤트를 참고하세요.