Contact Management

The Contact Management API lets you read and update the contact book that backs your messaging — contacts, groups, group memberships, and the custom fields that describe each contact. Use these endpoints to integrate Textingline with your CRM, sync contacts from a hosted form, or manage opt-in state programmatically.

The data model

There are five concepts you'll work with. Most integrations only touch the first three.

Contact

A person identified by their phone number in E.164 format (+18005551234). The contact carries profile fields (name, email, birthday, address), an opt-in state (active in groups, pending confirmation, or opted out), and custom-field values defined by your account schema.

The phone number is the canonical identifier — it appears in the URL of every contact endpoint as /v1/contacts/by-phone/{phoneNumber}. The API also returns a stable internal ID prefixed con_* for use in cross-references.

Group

A list of contacts. Groups are managed in your Textingline dashboard — the API exposes them as read-only. Each group has an optInType (SINGLE for explicit consent or DOUBLE for confirmation flow), a contactCount, and zero or more tags for sub-segmentation. Groups are addressed by a stable public ID prefixed grp_*.

Group membership

The link between a contact and a group. A membership is either active (the contact is opted in and will receive messages sent to the group) or pending (the contact has been invited via the double opt-in flow and hasn't yet replied YES). Use the membership endpoints to add or remove a contact from a group — never edit the membership through the contact endpoint.

Tag

A label attached to a contact's membership in a specific group. Tags are defined per group and used for sub-segmentation inside that group. The API surfaces tags read-only on the group response (tags[]) and on each membership (tags[] inside groups[] on a contact response).

Custom field

Operator-defined extra data per contact (e.g. Favorite Color, Birthday, T-Shirt Size). Defined in the dashboard, written and read via the contact endpoints. The schema is read-only via the API. Up to 7 custom fields per account. See Custom Fields for the full reference.

Consent and compliance

Every messaging operation in the API checks consent at send time. Two outcomes can block a write:

• HARD opt-out — the contact explicitly refused messages (texted STOP, opted out at a kiosk, or was flagged via carrier propagation). A HARD-opted-out contact cannot be re-enrolled by your account; only fresh consent from the contact themselves (replying YES to a new opt-in, opting back in via a hosted form) re-engages them. Attempting to add a HARD-opted-out contact to a group returns 409 ContactHardOptedOut (33035).
• PENDING memberships in other groups — contacts can't have pending memberships across multiple groups simultaneously. Adding such a contact to a new group returns 409 ContactPending (33036) until the existing pending memberships are resolved.

See Compliance for the messaging-side rules that pair with these contact-side checks.

Public identifiers

The API returns prefixed string IDs:

The phone number is the addressable identifier on contact endpoints (/contacts/by-phone/{phoneNumber}), so you rarely need to handle the con_* form directly. Groups are addressed by grp_* in URL paths.

How this relates to messaging

A contact must have an active membership in at least one group before any messaging endpoint will accept them as a recipient. Sending to a contact who isn't opted in (or who is HARD-opted-out) returns the compliance errors documented in Send a Message and Error Codes.

The recommended workflow for a new integration:

1. Make sure the relevant groups exist in your dashboard (LIST them via Groups to confirm).
2. Create or upsert each contact by phone.
3. Add each contact to a group via the membership endpoint — choose optInMode: DIRECT if you already collected consent, or optInMode: CONFIRM to have the platform send the opt-in SMS.
4. Send a single message, broadcast, or batch — recipients are checked against group membership and consent state at send time.

Section contents