Skip to main content
Records

Phone field value

Request
curl -X POST https://api.tapeapp.com/v1/record/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": {
"name": "Juliet Adams",
"phone": [
{ "type": "mobile", "phone": "+1 202 555 0143" },
{ "type": "work", "phone": "+1 202 555 0178" }
]
}
}'
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0143", "type": "mobile" },
{ "id": 101, "value": "+1 202 555 0178", "type": "work" }
]
}
]
}
Request
curl https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN"
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0143", "type": "mobile" },
{ "id": 101, "value": "+1 202 555 0178", "type": "work" }
]
}
]
}
Request
curl -X PUT https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": {
"phone": [
{ "id": 100, "type": "mobile", "phone": "+1 202 555 0199" },
{ "type": "main", "phone": "+1 202 555 0100" }
]
}
}'
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0199", "type": "mobile" },
{ "id": 102, "value": "+1 202 555 0100", "type": "main" }
]
}
]
}

Use a phone field value to read and write the phone numbers of a record.

The value of a phone field is a list of phone numbers in values. Each phone number has an id, the number in value and a type label in type.

Phone field value object
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{
"id": 100,
"value": "+1 202 555 0143",
"type": "mobile",
"created_at": "2026-11-11 10:15:00",
"created_at_utc": "2026-11-11 09:15:00",
"last_modified_at": "2026-11-11 10:15:00",
"last_modified_at_utc": "2026-11-11 09:15:00",
"created_by_user_id": 1,
"created_by_workflow_def_id": null,
"created_by_share_session_id": null,
"last_modified_by_user_id": 1,
"last_modified_by_workflow_def_id": null,
"last_modified_by_share_session_id": null
}
]
}

typestring

"phone" for a phone field.

Example value "phone"

field_typestring

"multi_phone".

Example value "multi_phone"

values[].idnumber

ID of the phone number. Send it with the phone number in an update to keep the ID.

Example value 100

values[].valuestring

The phone number as it was entered.

Example value "+1 202 555 0143"

values[].typestring

Type label: "mobile", "work", "home", "main", "work_fax", "home_fax", "pager", "other" or the text of a custom label of the field.

Example value "mobile"

values[].created_at, values[].last_modified_atstring

When the phone number was added and last changed, in your timezone.

Example value "2026-11-11 10:15:00"

values[].created_at_utc, values[].last_modified_at_utcstring

The same times in UTC.

Example value "2026-11-11 09:15:00"

values[].created_by_user_id, values[].last_modified_by_user_idnumber or null

ID of the user who added or last changed the phone number.

Example value 1

values[].created_by_workflow_def_id, values[].last_modified_by_workflow_def_idnumber or null

ID of the automation that added or last changed the phone number.

Example value null

values[].created_by_share_session_id, values[].last_modified_by_share_session_idstring or null

Session ID (UUID) of an anonymous visitor who added or changed the phone number through a shared link.

Example value null

Each field in a record response also contains the field's config. The examples on this page leave it out. They also leave out the times and author IDs of each phone number.

Record creation​

Use the create record endpoint to set phone numbers on a new record.

POST/v1/record/app/{app_id}api.tapeapp.com
Request
curl -X POST https://api.tapeapp.com/v1/record/app/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": {
"name": "Juliet Adams",
"phone": [
{ "type": "mobile", "phone": "+1 202 555 0143" },
{ "type": "work", "phone": "+1 202 555 0178" }
]
}
}'
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0143", "type": "mobile" },
{ "id": 101, "value": "+1 202 555 0178", "type": "work" }
]
}
]
}

The example sets two phone numbers in the "Phone" field (ID 3, type multi_phone, slug phone) of a new lead.

General behavior

  • Use the field ID or the field's slug (returned as external_id in records) as the key in fields.
  • Send an array of phone numbers. Each one is an object { "phone": "...", "type": "..." } or a string. value works in place of phone.
  • Send type in lowercase. Without type, or with a type Tape doesn't know, the phone number gets the label work.
  • The API accepts all eight built-in labels, even if the field's label_setting offers fewer.
  • A type that matches the text of a custom label of the field (not case-sensitive) gets that label.
  • If the field's label_setting is "none", Tape ignores type.
  • Tape stores the phone number as you send it. It removes spaces at the start and the end and skips empty phone numbers.
  • A required phone field needs at least one phone number on a new record. An empty array [] counts as missing.

Requirements: records:edit. Works with a personal access token, an OAuth access token or a user API key.

Errors

  • A type that matches more than one custom label of the field returns 400. Use a unique label.

See Errors for all error codes.

Record retrieval​

Use the retrieve record endpoint to read the phone numbers of a record.

GET/v1/record/{record_id}api.tapeapp.com
Request
curl https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN"
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0143", "type": "mobile" },
{ "id": 101, "value": "+1 202 555 0178", "type": "work" }
]
}
]
}

General behavior

  • A phone number without a label shows "type": "work". This includes all phone numbers of a field with "label_setting": "none".

Requirements: records:read. Works with a personal access token, an OAuth access token or a user API key.

Record update​

Use the update record endpoint to change the phone numbers of a record.

PUT/v1/record/{record_id}api.tapeapp.com
Request
curl -X PUT https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"fields": {
"phone": [
{ "id": 100, "type": "mobile", "phone": "+1 202 555 0199" },
{ "type": "main", "phone": "+1 202 555 0100" }
]
}
}'
Response
{
"record_id": 1,
"title": "Juliet Adams",
"fields": [
{
"field_id": 1,
"external_id": "name",
"label": "Name",
"type": "text",
"field_type": "single_text",
"values": [{ "value": "Juliet Adams" }]
},
{
"field_id": 3,
"external_id": "phone",
"label": "Phone",
"type": "phone",
"field_type": "multi_phone",
"values": [
{ "id": 100, "value": "+1 202 555 0199", "type": "mobile" },
{ "id": 102, "value": "+1 202 555 0100", "type": "main" }
]
}
]
}

The example changes the mobile number with ID 100, removes the work number and adds a main number.

General behavior

  • The new list replaces the old list. Tape removes phone numbers that aren't in the request.
  • A phone number sent with its id keeps that ID. Tape removes an entry with only id. A phone number without id becomes a new one.
  • To clear the field, send null or an empty array []. This also works for a required phone field.
  • Fields that aren't in the request keep their values.
Request: clear the field
{
"fields": {
"phone": null
}
}

A cleared field isn't in the fields of the response.

Requirements: records:edit. Works with a personal access token, an OAuth access token or a user API key.

Errors

Same errors as under Record creation. An update also returns these errors:

  • A phone number that isn't a string, like { "phone": 5 }, returns 400 with validation and the message Invalid input for Phone field with ID ….
  • An entry that's null, or an object without phone, value, type or id, returns the same error.

See Errors for all error codes.

Next steps​