API reference
chevron_right
Contacts

Upsert a contact

POSThttps://howdybell.com/api/v1/contacts/upsert

Create or update a contact based on email or phone number. If a contact with the provided email or phone exists, it is updated; otherwise, a new contact is created. At least one of email or phone is required for matching.

Request body

first_namestring
max 255 characters
last_namestring
max 255 characters
emailstring, nullable
max 255 charactersemail
phonestring, nullable
max 32 characters
companystring, nullable
max 255 characters
sourcestring, nullable
max 255 characters
intereststring, nullable
max 255 characters
address1string, nullable
max 255 characters
citystring, nullable
max 255 characters
statestring, nullable
max 2 characters
zipstring, nullable
max 10 characters
timezonestring, nullable
dndboolean
owner_user_idinteger, nullable
external_refstring, nullable
Your own ID for this contact, for example from another system. It must be unique across all contacts, deleted ones included; a duplicate answers 422.
max 255 characters
location_idintegerRequired
The location to work in. Must belong to your workspace.

Responses

200

contactobject
- idinteger
- namestring
- first_namestring
- last_namestring
- emailstring, nullable
- phone_displaystring, nullable
- intereststring, nullable
- sourcestring, nullable
- ownerobject, nullable
  - idinteger
  - namestring
- tagsarray of string
- stageobject, nullable
  - idinteger
  - namestring
  - kindstring
  - colorstring, nullable
- value_centsinteger
- last_activity_atstring, nullable
- next_taskobject, nullable
  - idinteger
  - titlestring
  - due_atstring, nullable
  - overdueboolean
- dndboolean
- companystring, nullable
- address1string, nullable
- citystring, nullable
- statestring, nullable
- zipstring, nullable
- timezonestring, nullable
- created_atstring, nullable
- updated_atstring, nullable
- opportunitiesarray of string
- tasksarray of string
- notesarray of string
- conversationsarray of string
- activitiesarray of string
createdboolean

201

contactobject
- idinteger
- namestring
- first_namestring
- last_namestring
- emailstring, nullable
- phone_displaystring, nullable
- intereststring, nullable
- sourcestring, nullable
- ownerobject, nullable
  - idinteger
  - namestring
- tagsarray of string
- stageobject, nullable
  - idinteger
  - namestring
  - kindstring
  - colorstring, nullable
- value_centsinteger
- last_activity_atstring, nullable
- next_taskobject, nullable
  - idinteger
  - titlestring
  - due_atstring, nullable
  - overdueboolean
- dndboolean
- companystring, nullable
- address1string, nullable
- citystring, nullable
- statestring, nullable
- zipstring, nullable
- timezonestring, nullable
- created_atstring, nullable
- updated_atstring, nullable
- opportunitiesarray of string
- tasksarray of string
- notesarray of string
- conversationsarray of string
- activitiesarray of string
createdboolean

422 Validation error

messagestring
Errors overview.
errorsobject
A detailed description of each field that failed validation.

RequestcURL

curl -X POST "https://howdybell.com/api/v1/contacts/upsert" \
  -H "Authorization: Bearer $HOWDYBELL_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "[email protected]",
  "phone": "+15125550123",
  "company": "string",
  "source": "string",
  "interest": "string",
  "address1": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "timezone": "string",
  "dnd": true,
  "owner_user_id": 1,
  "external_ref": "string",
  "location_id": 1
}'

Response200

{
  "contact": {
    "id": 1,
    "name": "Ada Lovelace",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "[email protected]",
    "phone_display": "+15125550123",
    "interest": "string",
    "source": "string",
    "owner": {
      "id": 1,
      "name": "Ada Lovelace"
    },
    "tags": [
      "string"
    ],
    "stage": {
      "id": 1,
      "name": "Ada Lovelace",
      "kind": "string",
      "color": "string"
    },
    "value_cents": 1,
    "last_activity_at": "string",
    "next_task": {
      "id": 1,
      "title": "string",
      "due_at": "string",
      "overdue": true
    },
    "dnd": true,
    "company": "string",
    "address1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "timezone": "string",
    "created_at": "string",
    "updated_at": "string",
    "opportunities": [
      "string"
    ],
    "tasks": [
      "string"
    ],
    "notes": [
      "string"
    ],
    "conversations": [
      "string"
    ],
    "activities": [
      "string"
    ]
  },
  "created": true
}