API REFERENCE

Contacts API

The SimplyRCS contacts API has 18 public endpoints. Every endpoint below is documented with its parameters, responses and an example request. The reference is public and needs no account; a scoped API key is required only to make live calls.

Contacts, tags, segments, imports, and subscription workflows.

Base URL https://api.simplyrcs.com · All 195 endpoints · Pricing

Endpoints in this section

GET /v1/contacts
POST /v1/contacts
GET /v1/contacts/attribute-keys
GET /v1/contacts/{id}
PUT /v1/contacts/{id}
DELETE /v1/contacts/{id}
GET /v1/contacts/{id}/consent
GET /v1/contacts/{id}/rcs-check
POST /v1/contacts/bulk/tag
DELETE /v1/contacts/bulk/tag
GET /v1/contacts/bulk/tag/{jobId}
POST /v1/contacts/import
GET /v1/contacts/import/{jobId}
GET /v1/tags
POST /v1/tags
DELETE /v1/tags/{id}
POST /v1/segments/preview
POST /v1/segments/resolve

GET/v1/contacts

List contacts

GET https://api.simplyrcs.com/v1/contacts · requires an API key

Query parameters

Name	Type	Required	Description
`page`	`integer`	No
`limit`	`integer`	No
`search`	`string`	No	Match against contact name or phone.
`tag`	`string`	No	Filter to contacts carrying this tag id.
`sortBy`	`"name" \| "phone" \| "createdAt"`	No
`sortOrder`	`"asc" \| "desc"`	No
`rcsCap`	`"true" \| "false"`	No	Filter by RCS capability.

Responses

Status	Returns	Description
`200`	`ContactListResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/contacts

Create a contact

POST https://api.simplyrcs.com/v1/contacts · requires an API key

Request body

ContactCreateRequest · optional

Responses

Status	Returns	Description
`201`	`Contact`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/contacts \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

GET/v1/contacts/attribute-keys

List distinct contact attribute keys

Returns the distinct custom attribute keys present across the organization's contacts (capped at 500).

GET https://api.simplyrcs.com/v1/contacts/attribute-keys · requires an API key

Responses

Status	Returns	Description
`200`	`ContactAttributeKeysResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/attribute-keys \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/contacts/{id}

Get a contact

GET https://api.simplyrcs.com/v1/contacts/{id} · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`Contact`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

PUT/v1/contacts/{id}

Update a contact

PUT https://api.simplyrcs.com/v1/contacts/{id} · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Request body

ContactUpdateRequest · optional

Responses

Status	Returns	Description
`200`	`Contact`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X PUT https://api.simplyrcs.com/v1/contacts/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

DELETE/v1/contacts/{id}

Delete a contact

DELETE https://api.simplyrcs.com/v1/contacts/{id} · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`ContactDeleteResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X DELETE https://api.simplyrcs.com/v1/contacts/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/contacts/{id}/consent

Get contact consent history

GET https://api.simplyrcs.com/v1/contacts/{id}/consent · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`object`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/{id}/consent \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/contacts/{id}/rcs-check

Check contact RCS capability

GET https://api.simplyrcs.com/v1/contacts/{id}/rcs-check · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`ContactRcsCheckResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/{id}/rcs-check \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/contacts/bulk/tag

Bulk-assign a tag to contacts

Small batches are tagged synchronously (200). Large batches are queued as a background job (202).

POST https://api.simplyrcs.com/v1/contacts/bulk/tag · requires an API key

Request body

ContactBulkTagRequest · optional

Responses

Status	Returns	Description
`200`	`ContactBulkTagSyncResponse`	Tag assigned synchronously
`202`	`ContactBulkTagJob`	Background bulk tag job queued
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/contacts/bulk/tag \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

DELETE/v1/contacts/bulk/tag

Bulk-remove a tag from contacts

DELETE https://api.simplyrcs.com/v1/contacts/bulk/tag · requires an API key

Request body

ContactBulkTagRequest · optional

Responses

Status	Returns	Description
`200`	`ContactBulkUntagResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X DELETE https://api.simplyrcs.com/v1/contacts/bulk/tag \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/contacts/bulk/tag/{jobId}

Get bulk tag job status

GET https://api.simplyrcs.com/v1/contacts/bulk/tag/{jobId} · requires an API key

Path parameters

Name	Type	Description
`jobId` required	`string`

Responses

Status	Returns	Description
`200`	`ContactBulkTagJob`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/bulk/tag/{jobId} \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/contacts/import

Create a contact import job

Uploads a CSV (max 10MB) and queues a background import job.

POST https://api.simplyrcs.com/v1/contacts/import · requires an API key

Request body

multipart/form-data · optional

Responses

Status	Returns	Description
`202`	`ContactImportJob`	Import job queued
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/contacts/import \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

GET/v1/contacts/import/{jobId}

Get a contact import job

GET https://api.simplyrcs.com/v1/contacts/import/{jobId} · requires an API key

Path parameters

Name	Type	Description
`jobId` required	`string`

Responses

Status	Returns	Description
`200`	`ContactImportJob`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/contacts/import/{jobId} \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/v1/tags

List contact tags

GET https://api.simplyrcs.com/v1/tags · requires an API key

Responses

Status	Returns	Description
`200`	`TagListResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X GET https://api.simplyrcs.com/v1/tags \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/tags

Create a contact tag

POST https://api.simplyrcs.com/v1/tags · requires an API key

Request body

TagCreateRequest · optional

Responses

Status	Returns	Description
`201`	`TagCreateResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/tags \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

DELETE/v1/tags/{id}

Delete a contact tag

DELETE https://api.simplyrcs.com/v1/tags/{id} · requires an API key

Path parameters

Name	Type	Description
`id` required	`string`

Responses

Status	Returns	Description
`200`	`TagDeleteResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X DELETE https://api.simplyrcs.com/v1/tags/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/v1/segments/preview

Preview a segment audience

POST https://api.simplyrcs.com/v1/segments/preview · requires an API key

Request body

SegmentQueryRequest · optional

Responses

Status	Returns	Description
`200`	`SegmentPreviewResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/segments/preview \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

POST/v1/segments/resolve

Resolve a segment audience

POST https://api.simplyrcs.com/v1/segments/resolve · requires an API key

Request body

SegmentQueryRequest · optional

Responses

Status	Returns	Description
`200`	`SegmentResolveResponse`	Successful response
`400`	`ErrorResponse`	Validation error
`401`	`ErrorResponse`	Authentication failed

Example request

curl -X POST https://api.simplyrcs.com/v1/segments/resolve \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Example request" }'

Other parts of the API

Get a free sender ID test Read the RCS API guide