Contacts

The Contacts API stores properties, labels and validated metadata. Collection endpoints are paginated.

Endpoints

Method	Path	Description
GET	/v2/contacts	List and filter contacts.
GET	/v2/contacts/{contactId}	Read a contact.
POST	/v2/contacts	Import a list of contacts.
PATCH	/v2/contacts/{contactId}	Update specified fields.
PUT	/v2/contacts/{contactId}	Replace the contact’s data.
DELETE	/v2/contacts/{contactId}	Delete a contact.

List and filter

curl "https://api.ip1sms.com/v2/contacts?meta&labels=Customers&start=0&limit=50" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Accept: application/json"

The collection can be filtered by:

• labels
• properties[property]
• metadata[property]

Metadata is included only when the meta query parameter is present.

/v2/contacts?labels=Customers
&properties[phoneNumber]=46700000000
&metadata[phoneNumber.isBlocked]=false
&meta

URL-encode brackets and values in a real client.

Read a contact

curl "https://api.ip1sms.com/v2/contacts/{contactId}?meta" \
  -H "Authorization: Bearer $IP1_TOKEN"

Import contacts

POST /v2/contacts accepts an array of contact documents. Imports are normally processed asynchronously. Add ?sync to process small collections immediately; the published recommendation limits synchronous imports to fewer than 1,000 contacts.

curl -X POST "https://api.ip1sms.com/v2/contacts" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "properties": {
        "phoneNumber": "46700000000",
        "email": "contact@example.com",
        "firstName": "Test"
      },
      "labels": ["Customers"]
    }
  ]'

Field	Required	Type	Description
properties	Yes	object	Contact data such as phoneNumber, firstName and email.
labels	No	string[]	Groups or categories.

Update a contact

Use PATCH for a partial update. According to the published documentation, specified null values are removed. Use PUT to replace the complete document.

curl -X PATCH "https://api.ip1sms.com/v2/contacts/{contactId}" \
  -H "Authorization: Bearer $IP1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": { "firstName": "Updated name" },
    "labels": ["Customers", "Active"]
  }'

Delete a contact

curl -X DELETE "https://api.ip1sms.com/v2/contacts/{contactId}" \
  -H "Authorization: Bearer $IP1_TOKEN"

For filter-based bulk deletion, see Contact tools.

Contact document

{
  "id": "contact_abc123",
  "ownerId": "ip1-XXXXX",
  "properties": {
    "phoneNumber": "46700000000",
    "email": "contact@example.com",
    "firstName": "Test",
    "department": "Support"
  },
  "metadata": {
    "phoneNumber": {
      "isPossiblePhoneNumber": "true",
      "isValidPhoneNumber": "true",
      "phoneNumberType": "MOBILE",
      "parsedMSISDN": "46700000000",
      "isBlocked": "false"
    }
  },
  "labels": ["Customers", "all"]
}

Metadata field	Type	Description
isPossiblePhoneNumber	stringified boolean	The number appears structurally possible.
isValidPhoneNumber	stringified boolean	The number has a valid format for the country.
phoneNumberType	string	For example MOBILE, FIXED_LINE or VOIP.
parsedMSISDN	string	Normalized MSISDN.
isBlocked	stringified boolean	The number is on the account’s blocklist.

The published API reference shows the metadata boolean values as strings. Type the client according to the actual response and avoid accidentally converting "false" to a true boolean value.