Phone field value
- cURL
- JSON
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" }
]
}
}'
{
"fields": {
"name": "Juliet Adams",
"phone": [
{ "type": "mobile", "phone": "+1 202 555 0143" },
{ "type": "work", "phone": "+1 202 555 0178" }
]
}
}
{
"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" }
]
}
]
}
curl https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"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" }
]
}
]
}
- cURL
- JSON
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" }
]
}
}'
{
"fields": {
"phone": [
{ "id": 100, "type": "mobile", "phone": "+1 202 555 0199" },
{ "type": "main", "phone": "+1 202 555 0100" }
]
}
}
{
"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.
{
"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.
field_typestring
"multi_phone".
values[].idnumber
ID of the phone number. Send it with the phone number in an update to keep the ID.
values[].valuestring
The phone number as it was entered.
values[].typestring
Type label: "mobile", "work", "home", "main", "work_fax", "home_fax", "pager", "other" or the text of a custom label of the field.
values[].created_at, values[].last_modified_atstring
When the phone number was added and last changed, in your timezone.
values[].created_at_utc, values[].last_modified_at_utcstring
The same times in UTC.
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.
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.
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.
| Property | Type | Description | Example value |
|---|---|---|---|
type | string | "phone" for a phone field. | "phone" |
field_type | string | "multi_phone". | "multi_phone" |
values[].id | number | ID of the phone number. Send it with the phone number in an update to keep the ID. | 100 |
values[].value | string | The phone number as it was entered. | "+1 202 555 0143" |
values[].type | string | Type label: "mobile", "work", "home", "main", "work_fax", "home_fax", "pager", "other" or the text of a custom label of the field. | "mobile" |
values[].created_at, values[].last_modified_at | string | When the phone number was added and last changed, in your timezone. | "2026-11-11 10:15:00" |
values[].created_at_utc, values[].last_modified_at_utc | string | The same times in UTC. | "2026-11-11 09:15:00" |
values[].created_by_user_id, values[].last_modified_by_user_id | number or null | ID of the user who added or last changed the phone number. | 1 |
values[].created_by_workflow_def_id, values[].last_modified_by_workflow_def_id | number or null | ID of the automation that added or last changed the phone number. | null |
values[].created_by_share_session_id, values[].last_modified_by_share_session_id | string or null | Session ID (UUID) of an anonymous visitor who added or changed the phone number through a shared link. | 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.
/v1/record/app/{app_id}api.tapeapp.com- cURL
- JSON
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" }
]
}
}'
{
"fields": {
"name": "Juliet Adams",
"phone": [
{ "type": "mobile", "phone": "+1 202 555 0143" },
{ "type": "work", "phone": "+1 202 555 0178" }
]
}
}
{
"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_idin records) as the key infields. - Send an array of phone numbers. Each one is an object
{ "phone": "...", "type": "..." }or a string.valueworks in place ofphone. - Send
typein lowercase. Withouttype, or with atypeTape doesn't know, the phone number gets the labelwork. - The API accepts all eight built-in labels, even if the field's
label_settingoffers fewer. - A
typethat matches the text of a custom label of the field (not case-sensitive) gets that label. - If the field's
label_settingis"none", Tape ignorestype. - 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
typethat matches more than one custom label of the field returns400. 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.
/v1/record/{record_id}api.tapeapp.comcurl https://api.tapeapp.com/v1/record/1 \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"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.
/v1/record/{record_id}api.tapeapp.com- cURL
- JSON
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" }
]
}
}'
{
"fields": {
"phone": [
{ "id": 100, "type": "mobile", "phone": "+1 202 555 0199" },
{ "type": "main", "phone": "+1 202 555 0100" }
]
}
}
{
"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
idkeeps that ID. Tape removes an entry with onlyid. A phone number withoutidbecomes a new one. - To clear the field, send
nullor an empty array[]. This also works for a required phone field. - Fields that aren't in the request keep their values.
{
"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 }, returns400withvalidationand the messageInvalid input for Phone field with ID …. - An entry that's
null, or an object withoutphone,value,typeorid, returns the same error.
See Errors for all error codes.