Create a contact

POST

/api/v2/contacts

curl --request POST \
  --url https://api.sipstack.com/api/v2/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "phoneNumber": "+14165550100", "firstName": "Jordan", "lastName": "Lee", "email": "jordan.lee@example.com", "tags": [ "newsletter" ], "consentStatus": "express", "consentMethod": "web_form", "consentDate": "2026-09-01" }'

import requests

url = "https://api.sipstack.com/api/v2/contacts"

payload = {
    "phoneNumber": "+14165550100",
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "jordan.lee@example.com",
    "tags": ["newsletter"],
    "consentStatus": "express",
    "consentMethod": "web_form",
    "consentDate": "2026-09-01"
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const url = 'https://api.sipstack.com/api/v2/contacts';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"phoneNumber":"+14165550100","firstName":"Jordan","lastName":"Lee","email":"jordan.lee@example.com","tags":["newsletter"],"consentStatus":"express","consentMethod":"web_form","consentDate":"2026-09-01"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.sipstack.com/api/v2/contacts',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  data: {
    phoneNumber: '+14165550100',
    firstName: 'Jordan',
    lastName: 'Lee',
    email: 'jordan.lee@example.com',
    tags: ['newsletter'],
    consentStatus: 'express',
    consentMethod: 'web_form',
    consentDate: '2026-09-01'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Creates a contact in your organization. Create-only — this endpoint never updates an existing contact. The phone number is normalized to E.164 before the uniqueness check; a live contact with the same number returns 409. Requires the contacts:write scope.

Authorizations

apiKeyAuth

Request Body^required

application/json

object

phoneNumber

required

Contact phone number — normalized to E.164 (a leading 1 is added to 10-digit numbers).

string

firstName

string

nullable

lastName

string

nullable

email

string format: email

nullable

tags

Array<string>

customFields

object

key

additional properties

any

consentStatus

Consent to text. Defaults to implied. Marketing campaigns send to US numbers only with express consent. Every express contact gets a consent history entry recording the method, the date and the API key that set it.

string

Allowed values: implied express none

consentMethod

How express consent was obtained. Used only with consentStatus: express (ignored otherwise). Optional: if you set express without it, the consent history records the method as api (declared by caller). Send it whenever you know it — a stated method is stronger evidence.

string

Allowed values: web_form paper_signature verbal_recorded other

consentMethodNote

Free-text detail on how consent was obtained (longer text is cut at 500 characters). Required when consentMethod is other.

string

<= 500 characters

consentDate

When express consent was obtained: YYYY-MM-DD or a full ISO 8601 timestamp. Cannot be in the future (a YYYY-MM-DD that is today in any timezone is accepted). Defaults to now. Used only with consentStatus: express.

string

impliedConsentBasis

The CASL basis for implied consent (Canada’s Anti-Spam Legislation). Used only with implied consent: sending it with consentStatus: express or none (or on a contact that is not implied) is a 400. Campaigns and drips count implied consent for as long as its basis lasts:

ebr_purchase — existing business relationship from a purchase or other transaction: 2 years from impliedConsentBasisDate (the most recent purchase).
ebr_contract — existing business relationship from a written contract: 2 years after impliedConsentBasisDate, the date the contract ends (may be in the future).
ebr_inquiry — an inquiry or application: 6 months from impliedConsentBasisDate.
nbr — non-business relationship: 2 years from impliedConsentBasisDate. Only for organizations SIPSTACK has marked as a charity, political organization, club or association; anyone else gets a 400.
conspicuous_publication — the person published their number conspicuously, without a statement that they do not want messages: no fixed expiry, and messages must relate to their role or business. consentEvidence is required.
disclosed_address — the person gave you their number without saying they do not want messages: no fixed expiry, same condition. consentEvidence is required.

An ebr_* or nbr basis without impliedConsentBasisDate is stored but treated as undeclared. A contact with no declared basis has undeclared implied consent, which lasts 6 months. Send null or "" to clear the basis. US numbers still need express consent for marketing whatever the basis.

string

nullable

Allowed values: ebr_purchase ebr_contract ebr_inquiry nbr conspicuous_publication disclosed_address

impliedConsentBasisDate

The date the basis runs from, YYYY-MM-DD or a full ISO 8601 timestamp: the most recent purchase (ebr_purchase), the contract end date (ebr_contract, which may be in the future), the inquiry (ebr_inquiry), the relationship (nbr), or when you observed the address (conspicuous_publication, disclosed_address). Cannot be in the future except for ebr_contract. Requires impliedConsentBasis.

string

nullable

consentEvidence

Free-text evidence for the consent, such as an invoice number, a form link or a reference (longer text is cut at 1,000 characters). Required for conspicuous_publication and disclosed_address. Send null or "" to clear it.

string

nullable <= 1000 characters

Examples

A contact with express consent

{
  "phoneNumber": "+14165550100",
  "firstName": "Jordan",
  "lastName": "Lee",
  "email": "jordan.lee@example.com",
  "tags": [
    "newsletter"
  ],
  "consentStatus": "express",
  "consentMethod": "web_form",
  "consentDate": "2026-09-01"
}

A contact with implied consent (the default)

{
  "phoneNumber": "+14165550100",
  "firstName": "Jordan",
  "lastName": "Lee"
}

Implied consent with a declared basis

{
  "phoneNumber": "+14165550100",
  "firstName": "Jordan",
  "lastName": "Lee",
  "consentStatus": "implied",
  "impliedConsentBasis": "ebr_purchase",
  "impliedConsentBasisDate": "2026-08-14",
  "consentEvidence": "Invoice 10442"
}

Responses

201

Contact created. data is the compact Contact subset (id, uuid, phone_number, names, email, tags, consent_status, consent_date, implied_consent_basis, implied_consent_basis_date, consent_evidence, created_at) — not the full record; read it back via GET /api/v2/contacts/{id} for the complete contact.

application/json

object

success

boolean

data

A contact record. POST /api/v2/contacts returns the compact subset (id, uuid, phone_number, names, email, tags, consent_status, consent_date, implied_consent_basis, implied_consent_basis_date, consent_evidence, created_at); the list/get/update endpoints return the full record below.

object

string format: uuid

uuid

string format: uuid

phone_number

string

first_name

string

nullable

last_name

string

nullable

email

string

nullable

business

string

nullable

tags

Array<string>

custom_fields

object

key

additional properties

any

consent_status

string

Allowed values: implied express none

consent_date

string format: date-time

nullable

implied_consent_basis

The declared CASL basis for implied consent; null = undeclared. See impliedConsentBasis on create.

string

nullable

Allowed values: ebr_purchase ebr_contract ebr_inquiry nbr conspicuous_publication disclosed_address

implied_consent_basis_date

The date the basis runs from (for ebr_contract, the contract end date).

string format: date-time

nullable

consent_evidence

Evidence recorded for the consent.

string

nullable

is_opted_out

boolean

is_blocked

boolean

is_archived

boolean

is_starred

boolean

last_contacted_at

string format: date-time

nullable

total_messages_sent

integer

total_messages_received

integer

source

How the contact was created (e.g. api).

string

nullable

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "data": {
    "phone_number": "+14165550100",
    "consent_status": "implied",
    "implied_consent_basis": "ebr_purchase"
  }
}

400

Phone number missing or invalid, or invalid consent fields: an unknown consentStatus or consentMethod, consentMethod: other without consentMethodNote, an unreadable or future consentDate, an unknown impliedConsentBasis, an impliedConsentBasis without implied consent, an impliedConsentBasisDate without a basis or unreadable or in the future (except ebr_contract), a missing consentEvidence for conspicuous_publication or disclosed_address, or nbr for an organization that is not eligible for it.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

401

Missing or invalid API key.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

403

API access is not enabled on your plan.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

409

A contact with this phone number already exists (including a soft-deleted one holding the key).

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

500

Internal error.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

503

MESSAGING_SETUP_UNAVAILABLE — your organization’s messaging account is set up automatically on its first contact write, and that setup failed. Nothing was written; retry shortly.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

Create a contact

Authorizations

Request Body required

Examples

Responses

201

Example

400

Example

401

Example

403

Example

409

Example

500

Example

503

Example

Request Body^required