Contacts API

Contacts allow you to tie individual Calls from many Contact Numbers back to one person. You can also tag Contacts, and calls from their Contact Numbers will automatically inherit the tags.

Get all Contacts

curl "https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1"

The above command returns JSON structured like this:

[
  {
    "contact": {
      "id": 2,
      "contact_numbers": [
        {
          "number": "+18668987878",
          "description": "Landline",
          "id": 2
        }
      ],
      "tag_values": [
        {
          "key": "name",
          "value": "Retreaver Support",
          "operator": "==",
          "id": 154060720
        }
      ]
    }
  }
]

Provides a complete list of Contacts. Results are paginated.

HTTP Request

GET https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1

Query Parameters

Get a Specific Contact by ID

curl "https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1"

The above command returns JSON structured like this:

{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18668987878",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}

Finds a Contact by its Retreaver ID.

HTTP Request

GET https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1

Create a Contact

curl -s \
    -X POST \
    https://api.retreaver.com/contacts.json \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}'

The above command returns JSON structured like this:

{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18668987878",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}

Creates a Contact and associated Contact Number(s).

HTTP Request

POST https://api.retreaver.com/contacts.json?api_key=[api_key]&company_id=1

Content-Type: application/json

{"contact":{"tag_list":"<<<name:Retreaver Support>>>","contact_numbers_attributes":[{"number":"8668987878", "description":"Landline"}]}}

Parameters

Nested Attribute: Contact Number

These are the phone numbers that are associated with your Contact.

tag_list notes

To set tags on a Contact, pass in a comma delineated, triple-angle-bracket enclosed string of tags as the tag_list value.

The system will create/find whatever tags you have set given this input without you having to track tag IDs. You must include the full list of tags you want set any time a tag_list parameter is passed in. To clear the tags, just pass in a blank string.

There is a limit of 100 tags added in this manner, but the system will automatically concatenate US zip geo tags.

Update a Contact

curl -s \
    -X PUT \
    https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}'

The above command returns JSON structured like this:

{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}

Changes any attributes you have passed in on the Contact. To change a Contact Number, you must pass in the ID of the existing Contact Number, or see below for an easier method.

HTTP Request

PUT https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1

Content-Type: application/json

{"contact":{"contact_numbers_attributes":[{"id":2,"number":"+18001234567"}]}}

Remove a Contact

curl -X DELETE https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1

Deletes the given Contact and all Contact Numbers associated with it.

HTTP Request

DELETE https://api.retreaver.com/contacts/2.json?api_key=[api_key]&company_id=1

Get a specific Contact by phone number

curl "https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1"

The above command returns JSON structured like this:

{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Retreaver Support",
        "operator": "==",
        "id": 154060720
      }
    ]
  }
}

Finds a Contact by phone number.

HTTP Request

GET https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1

Update a Contact by phone number

curl -s \
    -X PUT \
    https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1 \
    -H "Content-Type: application/json" \
    -d '{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}'

The above command returns JSON structured like this:

{
  "contact": {
    "id": 2,
    "contact_numbers": [
      {
        "number": "+18001234567",
        "description": "Landline",
        "id": 2
      }
    ],
    "tag_values": [
      {
        "key": "name",
        "value": "Invalid Number",
        "operator": "==",
        "id": 154060721
      }
    ]
  }
}

Updates a Contact by phone number. This endpoint acts as an upsert: if no Contact Number exists for the given phone number, a new Contact Number and Contact are created automatically.

HTTP Request

PUT https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1

Content-Type: application/json

{"contact":{"tag_list":"<<<name:Invalid Number>>>"}}

Delete a Contact by phone number

curl -X DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1

Deletes the contact associated with the phone number and all other contact numbers associated with the contact.

HTTP Request

DELETE https://api.retreaver.com/contact_numbers/+18001234567/contact.json?api_key=[api_key]&company_id=1