Skip to content
Contacts

Create a contact

POST
/{phone_number_id}/contacts
const url = 'https://api.kirimdev.com/v1/106540352242922/contacts';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': 'order-20260910-0001',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: '{"phone_number":"example","bsuid":"example","username":"example","name":"example","email":"hello@example.com","metadata":{"additionalProperty":"example"}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

Create a contact attached to the WhatsApp account identified by phone_number_id in the URL path.

phone_number_id
required

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

string
/^\d{6,20}$/
Example
106540352242922

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

Idempotency-Key

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

string
Example
order-20260910-0001

Optional retry key. Reusing the same key with the same method, path, and body within 24 hours returns the original response; reusing it for a different request returns 422.

Media type application/json
object
phone_number
string
bsuid
string
/^[A-Z]{2}\.(ENT\.)?[A-Za-z0-9]{1,128}$/
username
string
>= 1 characters <= 100 characters
name
string
>= 1 characters <= 200 characters
email
string | null format: email
<= 255 characters
metadata
object
key
additional properties
Example generated
{
"phone_number": "example",
"bsuid": "example",
"username": "example",
"name": "example",
"email": "hello@example.com",
"metadata": {
"additionalProperty": "example"
}
}

Contact created

Media type application/json
object
data
required
object
id
required
string
object
required
string
Allowed values: contact
phone_number
required

Phone number in E.164. NULL when the contact was created via BSUID (username-adopted user with no shared phone number). See docs/meta-docs/bsuid.md.

string | null
bsuid
required

Business-Scoped User ID. Populated by inbound webhooks or when the contact was created via BSUID. Format: {ISO alpha-2 country}.{alphanumeric ≤128}.

string | null
parent_bsuid
required

Parent BSUID (managed businesses only). Format: {ISO alpha-2 country}.ENT.{alphanumeric ≤128}.

string | null
username
required

WhatsApp username of the contact, if the user has adopted the username feature. Case-insensitive when comparing per Meta rules; . and _ are significant.

string | null
name
required
string | null
email
required
string | null
metadata
required
object | null
labels
required

Labels currently attached to this contact.

Array<object>
object
id
required
string
name
required
string
color
required
string
Allowed values: gray red orange amber yellow lime green emerald teal sky blue violet pink
whatsapp_account
required
object
phone_number
required
string | null
phone_number_id
required

Meta business_phone_number_id — use as the {phone_number_id} path segment in /v1/{phone_number_id}/... endpoints.

string | null
customer
required

End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts.

object
id
required
string
name
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
request_id
required

Unique request identifier to include when contacting support.

string
Example
{
"data": {
"id": "ctc_01HXYZABCDEFGHJKMNPQRSTVWX",
"object": "contact",
"phone_number": "+628123456789",
"bsuid": "US.13491208655302741918",
"parent_bsuid": "US.ENT.11815799212886844830",
"username": "pablomorales",
"labels": [
{
"id": "lbl_01HXYZABCDEFGHJKMNPQRSTVWX",
"name": "VIP",
"color": "gray"
}
],
"whatsapp_account": {
"phone_number_id": "106540352242922",
"customer": {
"id": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}
},
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

Validation failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A field value is invalid.

{
"error": {
"type": "invalid_request_error",
"code": "invalid_field_value",
"message": "A field value is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Authentication failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The provided API key is invalid.

{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Resource not found

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Resource not found.

{
"error": {
"type": "not_found",
"code": "resource_not_found",
"message": "Resource not found.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Conflict (e.g. template already exists, webhook subscription disabled, setup link inactive)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An identical request is still being processed. Retry later.

{
"error": {
"type": "conflict",
"code": "idempotency_in_progress",
"message": "An identical request is still being processed. Retry later.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.

{
"error": {
"type": "invalid_request_error",
"code": "whatsapp_number_not_verified",
"message": "The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Rate limit exceeded

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Rate limit exceeded.

{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Internal server error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An unexpected error occurred.

{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}