Create a contact at a phone number

post

https://platform.textingline.com/api/v1/contacts/by-phone/{phoneNumber}

Registers a new contact with the given E.164 phone number. The phone is the canonical identifier and comes from the URL — it is not accepted in the body. Any unknown property in the body is rejected with a 400.

customFields are validated against the user's current schema (same rules as PATCH — unknown indexes, type mismatches, etc. yield 33033 InvalidCustomField with a machine-readable details.reason).

If a contact with this phone already exists, the request is rejected with 409 ContactAlreadyExists (33037). To merge into an existing contact, GET /contacts/by-phone/{phoneNumber} then PATCH instead.

Creation does NOT trigger any consent flow — that happens only when the contact is enrolled into a group via POST .../groups/{groupId}.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

phoneNumber

string

required

Contact phone number in E.164 format (+ then country code and subscriber number).

Body Params

firstName

string

length ≤ 40

Contact's first name.

lastName

string

length ≤ 40

Contact's last name.

string

Contact's email address.

birthDate

string

Date of birth, strict YYYY-MM-DD format. Full ISO datetimes are rejected.

gender

string

enum

Contact's gender.

Allowed:

address

object

Contact's mailing address.

isFavorite

boolean

Whether the contact should be flagged as favorite.

customFields

object

Custom-field values keyed by label (the human-readable name you gave the field). Labels are matched case-insensitively after trimming whitespace. Discover available labels, types, and select options via GET /v1/contacts/custom-fields/schema. Value shape per schema field type: TEXT → string, NUMBER → number, BOOLEAN → boolean, DATE → YYYY-MM-DD string, SINGLE_SELECT → string matching one of options, MULTI_SELECT → array of strings each matching one of options. Unknown labels are rejected with 33033 InvalidCustomField and details.reason: "unknown_label".

Responses

201Contact created.

400Bad Request. Possible: 33003 Invalid phone number, 33033 Invalid custom field. Class-validator errors (e.g., invalid address.country — must be ISO 3166-1 alpha-2) return a standard validation envelope.

40933037 ContactAlreadyExists — a contact with this phone already exists.