Contacts

As the name suggests, contacts are the place where your customers' numbers are stored in Our voice. On this page, we'll dive into the different group terminals you can use to manage groups programmatically. We'll see how to query, create, update and delete contacts. The contact model contains all the information about your contacts, such as their first name, lasst name, phone number, and language. It also contains a reference to the conversation between you and the contact.

Properties

Name
id
Type
string
Description
Unique identifier for the contact.
Name
first_name
Type
string
Description
The first name for the contact.
Name
last_name
Type
string
Description
The last name for the contact.
Name
phone_number
Type
string
Description
The phone number for the contact. Must be at least 8 characters. Must not be greater than 15 characters.
Name
language
Type
string
Description
The language for the contact.
Name
custom_fields
Type
string
Description
The custom fields for the contact.
Name
created_at
Type
string
Description
TTimestamp of when the group was created.
Name
updated_at
Type
string
Description
Timestamp of when the group was updated.

POST/v1/contacts

Create a contact

This endpoint allows you to add a new contact to your contact list in Our voice. To add a contact, you must provide their Our voice username and phone number.

Required attributes

Name
phone_number
Type
string
Description
The phone number for the contact. Must be at least 8 characters. Must not be greater than 15 characters. Refer to the list at the top of this page to see which properties are included with group objects

Request

POST

/v1/contacts

curl https://api.getourvoice.com/v1/contacts
  --header "Authorization: Bearer {YOUR_AUTH_KEY}"
  --header "Content-Type: application/json"
  --header "Accept: application/json"
  --data "{
    \"phone_number": "22996XXXXXX",
    "first_name": "Nanisca",
    "last_name": "Agodjie",
  }"

Response (200)

{
  "data": {
    "id": "c61e3d84-4373-4078-acac-a8f3485c1b6c",
    "first_name": "Nanisca",
    "last_name": "Agodjie",
    "phone_number": "22996XXXXXX",
    "language": "french",
    "custom_fields": "{
      \"custom_field_1":"tenetur\", 
      \"custom_field_2\":\"sed\"
    }",
    "created_at": "2022-12-07T08:18:02.000000Z",
    "updated_at": "2022-12-07T08:18:02.000000Z"
  }
}

PUT/v1/contacts/{id}

Update a contact

This endpoint allows you to perform an update on a contact. It also takes a PATCH as a method.

Parameters

Name
id
Type
string
Description
The ID (uuid) of the contact.

Request

PUT

/v1/contacts/{id}

curl --request PUT \
  "https://api.getourvoice.com/v1/contacts/recusandae" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"\
  --data "{
    \"phone_number": "22996XXXXXX",
    "first_name": "Nanisca",
    "last_name": "Agodjie",
    "language": "french",
  }"

Response

{
  "data": {
      "id": "bd8ea025-06eb-4cf9-9e85-ed67f85d0f11",
      "first_name": "Nanisca",
      "last_name": "Agodjie",
      "phone_number": "22996XXXXXX",
      "language": "french",
      "custom_fields": "{\"custom_field_1\":\"occaecati\", \"custom_field_2\":\"numquam\"}",
      "created_at": "2022-12-07T08:18:02.000000Z",
      "updated_at": "2022-12-07T08:18:02.000000Z"
  }
}

DELETE/v1/contacts/{id}

Delete a contact

This endpoint allows you to delete a contact in Our voice. Note: This will also delete your sms with the given contact.

URL Parameters

Name
id
Type
string
Description
The ID (uuid) of the contact.

Request

DELETE

/v1/contacts/bd8ea025-06eb-4cf9-9e85

curl --request DELETE \
  "https://api.getourvoice.com/v1/contacts/bd8ea025-06eb-4cf9-9e85-ed67f85d0f11" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

PUT/v1/groups/{group}/contact/{contact}

Add a contact to group

This endpoint allows you to add a contact in a group.

Required attributes

Name
group
Type
string
Description
The group.
Name
contact
Type
string
Description
The contact.
Name
group_id
Type
string
Description
The group ID.
Name
contact_id
Type
string
Description
The contact ID.

Request

PUT

/v1/groups/{group}/contact/{contact}

curl --request PUT \
  "https://api.getourvoice.com/v1/groups/c6b52883-7f67-455e-8497-0ff3f09c3830/contact/5ad96684-e137-4e7a-884c-c2a69a6d880a" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
  \"group_id\": \"c6b52883-7f67-455e-8497-0ff3f09c3830\",
  \"contact_id\": \"5ad96684-e137-4e7a-884c-c2a69a6d880a\"
}"

Response

{
  "message": "Contact successfully added to group"
}

DELETE/v1/groups/{group}/contact/{contactId}

Remove contact from group

This endpoint allows you to remove a contact from a group in Our Voice.

Required attributes

Name
group
Type
string
Description
The group.
Name
contactId
Type
string
Description
The contact.
Name
group_id
Type
string
Description
The group ID.
Name
contact_id
Type
string
Description
The contact ID.

Request

DELETE

/v1/groups/{group}/contact/{contactId}

curl --request DELETE \
  "https://api.getourvoice.com/v1/groups/c6b52883-7f67-455e-8497-0ff3f09c3830/contact/5ad96684-e137-4e7a-884c-c2a69a6d880a" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
  \"group_id\": \"c6b52883-7f67-455e-8497-0ff3f09c3830\",
  \"contact_id\": \"5ad96684-e137-4e7a-884c-c2a69a6d880a\"
}"

Response

{
  "message": "Contact successfully removed from group"
}