Contacts

Bulk create contacts

Requires read_write. Limited to 20 imports/hour/user. Runs as one mutation. Processes 1–1000 rows with individual errors; duplicate channel or profile email skips the row and merges only tags. Remaining rows fail once the contact cap is reached. platform is ignored with accountId and rejected without it. Envelope profile/account errors fail the request.

post/v1/contacts/bulk

Request

  • Base URL: https://api.postzen.dev
  • URL: https://api.postzen.dev/v1/contacts/bulk
  • Auth: HTTP bearer

Request body

profileIdstring required

Owning profile id; immutable and must be in the API key scope.

accountIdstring

Connected account id; must belong to the same profile and caller.

platformstring

Ignored when accountId is supplied. Without accountId, this field is rejected with 400 validation; platform disambiguation is not supported.

Example request

{
  "profileId": "jd7profile123",
  "accountId": "jd7account123",
  "platform": "instagram",
  "contacts": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  ]
}

Response

Bulk create contacts.

messagestring required

Import outcome summary.

createdinteger required

Number of newly created contacts.

skippedinteger required

Number of duplicate contacts skipped, with tags merged.

errorsstring[] required

Per-row errors using 1-based row numbers.

totalinteger required

Number of submitted rows; equals created + skipped + errors.length.

Example response

{
  "message": "Contacts imported successfully",
  "created": 1,
  "skipped": 1,
  "errors": [
    "row 3: name is required"
  ],
  "total": 3
}

Changes

No recorded changes to this operation across all 1 revision of this API.