Skip to content

Commit ff88654

Browse files
VarshSureshclaude
VarshSuresh
and
claude
committed
Document bulk create and bulk delete contacts (Preview)
Adds POST /contacts/bulk (strict create) and POST /contacts/bulk/delete (permanent delete), mirroring the existing bulk update endpoint. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
1 parent 136d1a1 commit ff88654

1 file changed

Lines changed: 291 additions & 0 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9088,6 +9088,107 @@ paths:
90889088
schema:
90899089
"$ref": "#/components/schemas/error"
90909090
"/contacts/bulk":
9091+
post:
9092+
summary: Bulk create contacts
9093+
parameters:
9094+
- name: Intercom-Version
9095+
in: header
9096+
schema:
9097+
"$ref": "#/components/schemas/intercom_version"
9098+
tags:
9099+
- Contacts
9100+
operationId: BulkCreateContacts
9101+
description: |
9102+
You can bulk create contacts by submitting an array of contact objects. This is a **strict create** — it mirrors [Create a contact](/docs/references/preview/rest-api/api.intercom.io/contacts/createcontact) and never updates an existing contact.
9103+
9104+
The endpoint creates an async job that processes the items in the background. Use the returned job ID with `GET /contacts/bulk/{id}` to check the job status.
9105+
9106+
{% admonition type="info" name="Handling existing contacts" %}
9107+
If a contact already exists with the given `external_id` or `email` (including an archived contact), that item is rejected and the job's `state` ends as `completed_with_errors`. Genuinely new contacts in the same request are still created. There's currently no per-item error detail — the job `state` from `GET /contacts/bulk/{id}` is the only signal that one or more items were rejected.
9108+
9109+
Created contacts aren't returned with IDs in the response. Look them up afterwards with [Get a contact by External ID](/docs/references/preview/rest-api/api.intercom.io/contacts/getcontactbyexternalid) or [Search contacts](/docs/references/preview/rest-api/api.intercom.io/contacts/searchcontacts).
9110+
{% /admonition %}
9111+
9112+
{% admonition type="info" name="Limits" %}
9113+
- Maximum of 100 contacts per request.
9114+
- You can append tasks to an existing job by including `job.id` in the request body.
9115+
{% /admonition %}
9116+
requestBody:
9117+
content:
9118+
application/json:
9119+
schema:
9120+
"$ref": "#/components/schemas/bulk_create_contacts_request"
9121+
examples:
9122+
successful:
9123+
summary: Successful
9124+
value:
9125+
contacts:
9126+
- external_id: abc123
9127+
email: joe@bloggs.com
9128+
name: Joe Bloggs
9129+
- external_id: def456
9130+
email: maria@example.com
9131+
name: "María García"
9132+
role: lead
9133+
responses:
9134+
'202':
9135+
description: Accepted
9136+
content:
9137+
application/json:
9138+
examples:
9139+
successful:
9140+
value:
9141+
id: job_v2_2
9142+
type: contacts.bulk.job
9143+
state: running
9144+
created_at: 1713360000
9145+
updated_at: 1713360060
9146+
completed_at:
9147+
tasks:
9148+
- id: task_v2_2
9149+
item_count: 2
9150+
state: pending
9151+
created_at: 1713360000
9152+
started_at:
9153+
completed_at:
9154+
url: https://api.intercom.io/contacts/bulk/job_v2_2
9155+
schema:
9156+
"$ref": "#/components/schemas/contacts_bulk_job"
9157+
'401':
9158+
description: Unauthorized
9159+
content:
9160+
application/json:
9161+
examples:
9162+
Unauthorized:
9163+
value:
9164+
type: error.list
9165+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9166+
errors:
9167+
- code: unauthorized
9168+
message: Access Token Invalid
9169+
schema:
9170+
"$ref": "#/components/schemas/error"
9171+
'422':
9172+
description: Unprocessable Entity
9173+
content:
9174+
application/json:
9175+
examples:
9176+
missing_contacts:
9177+
value:
9178+
type: error.list
9179+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9180+
errors:
9181+
- code: missing_field
9182+
message: contacts field must be supplied
9183+
too_many_contacts:
9184+
value:
9185+
type: error.list
9186+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9187+
errors:
9188+
- code: invalid_parameter
9189+
message: maximum number of contacts per request is 100
9190+
schema:
9191+
"$ref": "#/components/schemas/error"
90919192
put:
90929193
summary: Bulk update contacts
90939194
parameters:
@@ -9270,6 +9371,108 @@ paths:
92709371
message: Access Token Invalid
92719372
schema:
92729373
"$ref": "#/components/schemas/error"
9374+
"/contacts/bulk/delete":
9375+
post:
9376+
summary: Bulk delete contacts
9377+
parameters:
9378+
- name: Intercom-Version
9379+
in: header
9380+
schema:
9381+
"$ref": "#/components/schemas/intercom_version"
9382+
tags:
9383+
- Contacts
9384+
operationId: BulkDeleteContacts
9385+
description: |
9386+
You can permanently delete contacts in bulk by submitting an array of contact `id`s. This mirrors [Delete a contact](/docs/references/preview/rest-api/api.intercom.io/contacts/deletecontact) — deleted contacts are **not restorable**.
9387+
9388+
The endpoint creates an async job that processes the deletes in the background. Use the returned job ID with `GET /contacts/bulk/{id}` to check the job status.
9389+
9390+
{% admonition type="warning" name="Permanent deletion" %}
9391+
Unlike archiving, permanently deleted contacts cannot be recovered. A contact that doesn't exist, or can't be deleted, fails that item and the job's `state` ends as `completed_with_errors` (visible via `GET /contacts/bulk/{id}`) without failing the rest of the batch. Contacts with a `visitor` role are silently skipped rather than counted as failures.
9392+
{% /admonition %}
9393+
9394+
{% admonition type="info" name="Limits" %}
9395+
- Maximum of 100 contacts per request.
9396+
- You can append tasks to an existing job by including `job.id` in the request body.
9397+
{% /admonition %}
9398+
requestBody:
9399+
content:
9400+
application/json:
9401+
schema:
9402+
"$ref": "#/components/schemas/bulk_delete_contacts_request"
9403+
examples:
9404+
successful:
9405+
summary: Successful
9406+
value:
9407+
contacts:
9408+
- id: abc123
9409+
- id: def456
9410+
responses:
9411+
'202':
9412+
description: Accepted
9413+
content:
9414+
application/json:
9415+
examples:
9416+
successful:
9417+
value:
9418+
id: job_v2_3
9419+
type: contacts.bulk.job
9420+
state: running
9421+
created_at: 1713360000
9422+
updated_at: 1713360060
9423+
completed_at:
9424+
tasks:
9425+
- id: task_v2_3
9426+
item_count: 2
9427+
state: pending
9428+
created_at: 1713360000
9429+
started_at:
9430+
completed_at:
9431+
url: https://api.intercom.io/contacts/bulk/job_v2_3
9432+
schema:
9433+
"$ref": "#/components/schemas/contacts_bulk_job"
9434+
'401':
9435+
description: Unauthorized
9436+
content:
9437+
application/json:
9438+
examples:
9439+
Unauthorized:
9440+
value:
9441+
type: error.list
9442+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9443+
errors:
9444+
- code: unauthorized
9445+
message: Access Token Invalid
9446+
schema:
9447+
"$ref": "#/components/schemas/error"
9448+
'422':
9449+
description: Unprocessable Entity
9450+
content:
9451+
application/json:
9452+
examples:
9453+
missing_contacts:
9454+
value:
9455+
type: error.list
9456+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9457+
errors:
9458+
- code: missing_field
9459+
message: contacts field must be supplied
9460+
missing_id:
9461+
value:
9462+
type: error.list
9463+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9464+
errors:
9465+
- code: missing_field
9466+
message: contacts must be identified by id
9467+
too_many_contacts:
9468+
value:
9469+
type: error.list
9470+
request_id: 2859da57-c83f-405c-8166-240a312442a3
9471+
errors:
9472+
- code: invalid_parameter
9473+
message: maximum number of contacts per request is 100
9474+
schema:
9475+
"$ref": "#/components/schemas/error"
92739476
"/content/bulk_actions":
92749477
post:
92759478
summary: Run a bulk action on Knowledge Hub content (Preview)
@@ -26719,6 +26922,94 @@ components:
2671926922
type: array
2672026923
items:
2672126924
$ref: "#/components/schemas/brand"
26925+
bulk_create_contacts_request:
26926+
title: Bulk Create Contacts Request
26927+
type: object
26928+
description: Request body for bulk creating contacts.
26929+
required:
26930+
- contacts
26931+
properties:
26932+
contacts:
26933+
type: array
26934+
description: An array of contact objects to create. Maximum 100 contacts
26935+
per request.
26936+
maxItems: 100
26937+
items:
26938+
type: object
26939+
properties:
26940+
external_id:
26941+
type: string
26942+
description: A unique identifier for the contact which you have
26943+
defined.
26944+
example: abc123
26945+
email:
26946+
type: string
26947+
description: The contact's email address.
26948+
example: joe@example.com
26949+
name:
26950+
type: string
26951+
description: The contact's name.
26952+
example: Joe Bloggs
26953+
role:
26954+
type: string
26955+
description: The contact's role. One of `user` or `lead`. Leads
26956+
are exempt from the uniqueness check described above.
26957+
example: user
26958+
phone:
26959+
type: string
26960+
description: The contact's phone number.
26961+
language_override:
26962+
type: string
26963+
description: A preferred language setting for the contact, used by
26964+
the Intercom Messenger.
26965+
example: fr
26966+
custom_attributes:
26967+
type: object
26968+
description: Custom attributes to set on the contact.
26969+
signed_up_at:
26970+
type: integer
26971+
description: The time the contact signed up, in Unix timestamp format.
26972+
last_seen_at:
26973+
type: integer
26974+
description: The time the contact was last seen, in Unix timestamp
26975+
format.
26976+
job:
26977+
type: object
26978+
description: Optional. Include to append tasks to an existing job.
26979+
properties:
26980+
id:
26981+
type: string
26982+
description: The ID of an existing bulk job to append to.
26983+
example: job_v2_1
26984+
bulk_delete_contacts_request:
26985+
title: Bulk Delete Contacts Request
26986+
type: object
26987+
description: Request body for permanently bulk deleting contacts.
26988+
required:
26989+
- contacts
26990+
properties:
26991+
contacts:
26992+
type: array
26993+
description: An array of contacts to delete, each identified by `id`.
26994+
Maximum 100 contacts per request.
26995+
maxItems: 100
26996+
items:
26997+
type: object
26998+
required:
26999+
- id
27000+
properties:
27001+
id:
27002+
type: string
27003+
description: The unique identifier for the contact.
27004+
example: abc123
27005+
job:
27006+
type: object
27007+
description: Optional. Include to append tasks to an existing job.
27008+
properties:
27009+
id:
27010+
type: string
27011+
description: The ID of an existing bulk job to append to.
27012+
example: job_v2_1
2672227013
bulk_update_contacts_request:
2672327014
title: Bulk Update Contacts Request
2672427015
type: object

0 commit comments

Comments
 (0)