Update a contact

PATCH

/api/v2/contacts/{id}

curl --request PATCH \
  --url https://api.sipstack.com/api/v2/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "firstName": "Jordan", "lastName": "Lee", "email": "jordan.lee@example.com", "business": "Lee Consulting", "tags": [ "vip", "newsletter" ], "customFields": { "plan": "enterprise" } }'

import requests

url = "https://api.sipstack.com/api/v2/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"

payload = {
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "jordan.lee@example.com",
    "business": "Lee Consulting",
    "tags": ["vip", "newsletter"],
    "customFields": { "plan": "enterprise" }
}
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.json())

const url = 'https://api.sipstack.com/api/v2/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"firstName":"Jordan","lastName":"Lee","email":"jordan.lee@example.com","business":"Lee Consulting","tags":["vip","newsletter"],"customFields":{"plan":"enterprise"}}'
};

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: 'PATCH',
  url: 'https://api.sipstack.com/api/v2/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  data: {
    firstName: 'Jordan',
    lastName: 'Lee',
    email: 'jordan.lee@example.com',
    business: 'Lee Consulting',
    tags: ['vip', 'newsletter'],
    customFields: {plan: 'enterprise'}
  }
};

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

Updates the mutable fields of a contact (contacts:write). phoneNumber is not mutable here — it is the dedupe key. 404 when absent / cross-org / soft-deleted; 400 when no updatable field is provided. Consent (consentStatus and the express consentMethod, consentMethodNote, consentDate, and the implied impliedConsentBasis, impliedConsentBasisDate, consentEvidence) is written only when it changes.

Authorizations

apiKeyAuth

Parameters

Path Parameters

required

string format: uuid

Request Body^required

application/json

Mutable contact fields (all optional; at least one must be present). phoneNumber is not mutable here — it is the dedupe key; use create/delete to change it.

object

firstName

string

nullable

lastName

string

nullable

email

string

nullable

business

string

nullable

tags

Array<string>

customFields

object

key

additional properties

any

consentStatus

Consent to text. Consent is written only when it changes: re-sending the contact’s current status (for example, a sync that sends every field) leaves consent_date untouched, so the 24-month window for implied consent is not restarted. For a contact that is already express, sending consentMethod, consentMethodNote or consentDate records a new basis only if one of them differs; a field you leave out keeps its recorded value. Each change is added to the contact’s consent history with the API key that made 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

Update contact details

{
  "firstName": "Jordan",
  "lastName": "Lee",
  "email": "jordan.lee@example.com",
  "business": "Lee Consulting",
  "tags": [
    "vip",
    "newsletter"
  ],
  "customFields": {
    "plan": "enterprise"
  }
}

Record express consent

{
  "consentStatus": "express",
  "consentMethod": "paper_signature",
  "consentMethodNote": "Signed the sign-up sheet at the front desk",
  "consentDate": "2026-09-01"
}

Responses

200

The updated 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

A field was the wrong type, no updatable fields were provided, or invalid consent fields: an unknown consentStatus or consentMethod, consentMethod: other without consentMethodNote, an unreadable or future consentDate, a consent method/date without consentStatus, or invalid consent basis fields (the same rules as on create; evidence and nbr are checked against what the contact will have after the update).

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"
}

404

Contact not found in your organization.

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"
}

Update a contact

Authorizations

Parameters

Path Parameters

Request Body required

Examples

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

Request Body^required