Opt a contact back into messaging

POST

/api/v2/contacts/{id}/opt-in

curl --request POST \
  --url https://api.sipstack.com/api/v2/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/opt-in \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "reason": "Signed consent form received at the front desk on 2026-09-17", "evidence": { "type": "signed_consent", "evidenceDate": "2026-09-17T14:00:00Z", "reference": "Front-desk consent form 0042" } }'

import requests

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

payload = {
    "reason": "Signed consent form received at the front desk on 2026-09-17",
    "evidence": {
        "type": "signed_consent",
        "evidenceDate": "2026-09-17T14:00:00Z",
        "reference": "Front-desk consent form 0042"
    }
}
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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/opt-in';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"reason":"Signed consent form received at the front desk on 2026-09-17","evidence":{"type":"signed_consent","evidenceDate":"2026-09-17T14:00:00Z","reference":"Front-desk consent form 0042"}}'
};

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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/opt-in',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  data: {
    reason: 'Signed consent form received at the front desk on 2026-09-17',
    evidence: {
      type: 'signed_consent',
      evidenceDate: '2026-09-17T14:00:00Z',
      reference: 'Front-desk consent form 0042'
    }
  }
};

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

Reverses an opt-out: removes the contact’s number from the STOP list and sets is_opted_out back to false, so the contact is eligible to receive messages again. Only do this with a genuine, documented re-consent. Requires contacts:write. 404 when the contact isn’t your organization’s.

If the contact opted out themselves (texted STOP, opted out with their carrier, or a plain-language opt-out request you confirmed), you must send a reason of at least 20 characters and evidence that they agreed again after opting out. Both are saved to the contact’s consent history with the API key that made the change, and SIPSTACK is notified. Without them the request is refused with 400 OPT_OUT_OVERRIDE_EVIDENCE_REQUIRED (the body lists each problems item) and nothing changes. Neither is needed when the opt-out was made another way (for example by you, or after a delivery bounce). A contact who texts START is opted back in automatically.

Authorizations

apiKeyAuth

Parameters

Path Parameters

required

string format: uuid

Request Body

application/json

object

reason

Why the contact may receive messages again — for example, how they gave permission. Required when the contact opted out by texting STOP. Leading and trailing spaces are trimmed; text beyond 500 characters is not stored.

string

<= 500 characters

Example

Signed consent form received at the front desk on 2026-09-17

evidence

Proof the contact agreed again after opting out. Required when the contact opted out themselves.

object

type

required

string

Allowed values: signed_consent consumer_start verbal_recorded

Example

signed_consent

evidenceDate

required

When they agreed again (ISO 8601). Must be after the opt-out and not in the future.

string

Example

2026-09-17T14:00:00Z

reference

required

Where the proof is kept (form number, recording id, …).

string

<= 256 characters

Example

Front-desk consent form 0042

Responses

200

Contact opted in.

application/json

object

success

boolean

message

string

Example

{
  "message": "Contact opted in successfully"
}

400

OPT_OUT_OVERRIDE_EVIDENCE_REQUIRED — the contact opted out themselves and the request is missing a long enough reason or valid evidence. Nothing was changed.

application/json

object

success

boolean

code

string

problems

Array<string>

Allowed values: reason_too_short evidence_missing evidence_type_invalid evidence_date_invalid evidence_date_in_future evidence_not_after_opt_out evidence_reference_missing

error

string

Example

{
  "success": false,
  "code": "OPT_OUT_OVERRIDE_EVIDENCE_REQUIRED",
  "problems": [
    "reason_too_short"
  ],
  "error": "This contact opted out themselves (STOP, their carrier, or a confirmed opt-out request). To opt them back in, give a reason of at least 20 characters and proof that they agreed again after opting out (a START text, a signed consent, or a recorded verbal consent), with its date and a reference."
}

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

The key is missing the contacts:write scope, or the Flare API tier is not 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"
}