Avochato API

Welcome!

If anything isn’t working as documented, please message Avochato Support @ 415-214-8977.

To use the Avochato API, you will need a pair of Auth ID and Secret tokens. Tokens are account-specific and are bound to your specific User, so a pair of tokens must be generated per account. To generate a new set of tokens, please log into www.avochato.com and go to Settings > API Access.

Getting Started

To get started, here are some common routes you may want to check out:

  • Contacts, which represent a unique external phone number that is interacting with your Avochato number
  • Tickets, which represent a conversation between an Account and a Contact
  • Messages, which represent the messages sent and received by your Avochato number
  • Broadcasts, which let you create and schedule messages to an audience of Contacts
  • Users, which represent team members who have access to your Avochato account
  • User Roles, which are notification preference templates you can apply when adding new users

The Default Scope of API Credentials

One set of API credentials is required to use the Avochato API. By default, your API credentials are scoped to the inbox they were created in, and all the actions taken are associated with the user who was assigned to the credentials. Any actions you take will be scoped to that inbox and its settings and capabilities.

For example, any contacts, messages, broadcasts etc that you create with the API will appear in the inbox associated with these credentials.

To view which inbox your API credentials are scoped to, you can send a GET request to the /whoami route.

If the user associated with a pair of API credentials is removed from an inbox, or the credentials are deleted, they will cease to function in that inbox and you will receive an authentication error when attempting to use the API.

Accessing other inboxes with the “subdomain” parameter

You can scope your request to a different inbox using the optional “subdomain” parameter as part of the body of any API request e.g. “subdomain=my_avochato_inbox”.

Use the List Accounts route to view the list of inboxes you have access to, including the list of subdomains.

You may use the subdomain parameter for any request to specify any inbox that your user is a member of. This must equal the subdomain (/accounts/my_avochato_inbox/tickets) of an inbox.

If you cannot access an inbox using your credentials, make sure you are spelling the subdomain correctly and that your user has access to that inbox.

User Permission Roles

Every user in an Avochato account is assigned a permission role that controls what actions they can perform. This is set via the role parameter when adding or updating users.

Role Description
member Can view and respond to conversations. Default role when adding a user.
manager Everything a member can do, plus manage team settings (add/remove users, update roles for members). Cannot promote users to owner or modify existing owners.
owner Full account control, including billing and all management actions. Can promote users to any role including owner.

Role enforcement in the API: - Any management actions (adding users, updating roles, disabling users) require the API credentials to belong to a manager or owner. - Only owner-role users (or Avochato admins) can assign or change the owner role. - Only owner-role users (or Avochato admins) can modify or delete other owner-role users.

Setting a role when adding a user — include role in the body of POST /v1/users: role=manager

Changing a user’s role — use PUT /v1/users/:id with the new role: role=owner

User Role Notification Templates

In addition to permission roles, Avochato supports custom User Role templates (configured in your inbox under Settings > Manage Roles). These are named templates that set a new user’s default notification preferences — which alerts they receive for SMS, calls, push notifications, and more.

These are separate from the member/manager/owner permission role. You can use both together when adding a user.

To use a notification template when adding a user: 1. Call GET /v1/user_roles to list your templates and get their encoded IDs. 2. Pass user_role_id along with role when calling POST /v1/users.

role=member user_role_id=<encoded_id_from_get_v1_user_roles>

user_role_id only takes effect when a brand-new Avochato user is created — existing users already have their own notification settings.

See the User Roles and Users sections for the full endpoint details.

Rate limits

The API is subject to rate-limiting - sending too many requests too quickly will return a 429 HTTP response and the API request will be ignored.

If you receive a rate limit error while using the API, stop making requests immediately and slow down the speed at which you are sending requests.

Accounts

Fetch Accounts

Fetch one or more Accounts by their unique subdomain

Endpoint

GET /v1/accounts/:ids

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of Account subdomains to fetch
page Page to request

Request

Route

GET /v1/accounts/test-account%2Caccount_31?auth_id=Pe6bez9Xwy&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=Pe6bez9Xwy
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/accounts/test-account%2Caccount_31?auth_id=Pe6bez9Xwy&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 78f94be2-1062-4534-a8d9-28858e2c1177
X-Runtime: 0.042912
Content-Length: 313

Body

{
  "status": 200,
  "data": {
    "accounts": [
      {
        "id": "Pe6bez9Xwy",
        "subdomain": "account_31",
        "name": "Account 31",
        "phone": null,
        "created_at": 1781280060.944818,
        "tcr_campaign_id": null
      },
      {
        "id": "3OLb4Y94Ym",
        "subdomain": "test-account",
        "name": "Test Account",
        "phone": null,
        "created_at": 1781280060.965865,
        "tcr_campaign_id": null
      }
    ]
  },
  "page": 1
}

List Accounts

List each of the Accounts this API Key can access

Endpoint

GET /v1/accounts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
page Page to request

Request

Route

GET /v1/accounts?auth_id=EZA9P5Jrwg&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=EZA9P5Jrwg
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/accounts?auth_id=EZA9P5Jrwg&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: fc6f3df3-021c-4b57-aca8-19ef1096fba5
X-Runtime: 0.024348
Content-Length: 313

Body

{
  "status": 200,
  "data": {
    "accounts": [
      {
        "id": "AEgb5r9ejL",
        "subdomain": "account_33",
        "name": "Account 33",
        "phone": null,
        "created_at": 1781280061.105386,
        "tcr_campaign_id": null
      },
      {
        "id": "zPG9yg8aO0",
        "subdomain": "test-account",
        "name": "Test Account",
        "phone": null,
        "created_at": 1781280061.125272,
        "tcr_campaign_id": null
      }
    ]
  },
  "page": 1
}

List Current API Credentials

List info about this API Key and its account

Endpoint

GET /v1/whoami

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field

Request

Route

GET /v1/whoami?auth_id=3OLb4Y94Ym&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=3OLb4Y94Ym
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/whoami?auth_id=3OLb4Y94Ym&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 75f386e9-c5f1-449d-a592-98bca4212e5b
X-Runtime: 0.017149
Content-Length: 485

Body

{
  "status": 200,
  "data": {
    "account": {
      "id": "EZA9P5Jrwg",
      "subdomain": "account_32",
      "name": "Account 32",
      "phone": null,
      "created_at": 1781280061.0392902,
      "tcr_campaign_id": null
    },
    "user": {
      "email": "person_36@example.com",
      "id": "43y83xbVNM",
      "name": "Person 26",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280061.04336,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false
    },
    "origin": "api",
    "created_at": "2026-06-12T09:01:01.046-07:00"
  }
}

Broadcasts

A Broadcast is a message that is delivered to one or more contacts. In order to send a broadcast via the API, you must
1) Create a broadcast
2) Add contacts to the broadcast audience
3)Publish your broadcast (either ASAP or in the future).

The recipients will each receive your broadcast’s message on their device in a 1-on-1 conversation with your Avochato number.
You can use variables like $first_name to customize the content of the message.
Broadcasts with large audiences or long message content will take longer to deliver to the entire audience. Broadcasts cannot be sent to groups.

Audience Count

Get Broadcast audience count

Endpoint

GET /v1/broadcasts/:id/audience_count

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field

Request

Route

GET /v1/broadcasts/0nMJLk9vZ2/audience_count?auth_id=WAnJQLm9y1&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=WAnJQLm9y1
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/broadcasts/0nMJLk9vZ2/audience_count?auth_id=WAnJQLm9y1&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 847e13c5-07c8-44d9-8f72-3f781785512b
X-Runtime: 0.020929
Content-Length: 20

Body

{
  "data": {
    "count": 1
  }
}

Create Broadcast

Create a new broadcast

Endpoint

POST /v1/broadcasts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
message required String, the Message you want to broadcast (1600 character limit)
media_url Url of media to send in MMS (500kb limit)
status_callback Url to send status updates for each message sent by this broadcast
name String, name of this broadcast
via_tags Comma-separated list of contact tags to add to this broadcast
via_contact_ids Comma-separated list of contact ids to add to this broadcast
via_phone_numbers Comma-separated list of phone_numbers to add to this broadcast
via_field[field] String, either name ,phone ,phone_formatted ,email ,company ,street ,city ,state ,country ,zip ,priority ,opted_out ,salesforce_object_id ,salesforce_object_type, OR Custom Variable name
via_field[value] String, match all contacts with a given field which matches this value exactly

Request

Route

POST /v1/broadcasts

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "2jRbkR681P",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "message": "new test message",
  "media_url": "https://somesite.com/pretty.jpg",
  "status_callback": "https://somesite.com/some_callback_route",
  "name": "My New Broadcast",
  "via_tags": "tag1,tag2",
  "via_contact_ids": "3OLb4WY84Y",
  "via_phone_numbers": "5105551234,4155551234",
  "via_field[field]": "email",
  "via_field[value]": "bob@mctest.com"
}

cURL

curl "https://www.avochato.com/v1/broadcasts" -d '{"auth_id":"2jRbkR681P","auth_secret":"YYYYYYYYYYYYYYYYYYYY","message":"new test message","media_url":"https://somesite.com/pretty.jpg","status_callback":"https://somesite.com/some_callback_route","name":"My New Broadcast","via_tags":"tag1,tag2","via_contact_ids":"3OLb4WY84Y","via_phone_numbers":"5105551234,4155551234","via_field[field]":"email","via_field[value]":"bob@mctest.com"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 285fbe99-c1c9-4b2a-9db6-45d8fbc1b7be
X-Runtime: 0.189266
Content-Length: 861

Body

{
  "status": 200,
  "data": {
    "broadcast": {
      "id": "ezjJ7L85yZ",
      "name": "My New Broadcast",
      "message": "new test message",
      "media_url": "https://somesite.com/pretty.jpg",
      "estimated_segments_sms": 1,
      "estimated_segments_mms": 1,
      "status_callback": "https://somesite.com/some_callback_route",
      "status": "draft",
      "created_at": 1781280064.042513,
      "updated_at": 1781280064.042513,
      "scheduled_for": 0.0,
      "completed_at": null,
      "user": {
        "email": "person_53@example.com",
        "id": "0N6bwZR8DM",
        "name": "Person 37",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280063.89234,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      },
      "assign_to_user_id": null,
      "boost_multiplier": 1,
      "sms_errors": {},
      "mms_errors": {},
      "audience": 0,
      "contacts_count": 0,
      "attempted": 0,
      "delivered": 0,
      "undelivered": 0,
      "responded": 0,
      "replied_stop": 0,
      "pending_contacts_count": 3
    }
  }
}

Fetch Broadcast(s)

Fetch one or more broadcasts based on their ids

Endpoint

GET /v1/broadcasts/:ids

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of Broadcast ids to fetch
page Page number to request

Request

Route

GET /v1/broadcasts/enL8alJ7Nw%2CPxB9NV9YOy?auth_id=PxB9NQVbYO&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=PxB9NQVbYO
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/broadcasts/enL8alJ7Nw%2CPxB9NV9YOy?auth_id=PxB9NQVbYO&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: d1b30d8a-93f8-49b6-9209-0545ed893a9d
X-Runtime: 0.113345
Content-Length: 1531

Body

{
  "status": 200,
  "data": {
    "broadcasts": [
      {
        "id": "enL8alJ7Nw",
        "name": null,
        "message": "Sunt unde odit repellat.",
        "media_url": null,
        "estimated_segments_sms": 1,
        "estimated_segments_mms": 0,
        "status_callback": null,
        "status": "draft",
        "created_at": 1781280064.469105,
        "updated_at": 1781280064.469105,
        "scheduled_for": 1781884864.4688141,
        "completed_at": null,
        "user": {
          "email": "person_55@example.com",
          "id": "k5V9Vxz8lr",
          "name": "Person 39",
          "image_url": null,
          "signed_in_at": null,
          "avobot_id": null,
          "phone": null,
          "phone_formatted": null,
          "created_at": 1781280064.46497,
          "require_2fa": true,
          "mfa_app_valid": false,
          "phone_valid": false
        },
        "assign_to_user_id": null,
        "boost_multiplier": 1,
        "sms_errors": {},
        "mms_errors": {},
        "audience": 1,
        "contacts_count": 1,
        "attempted": 0,
        "delivered": 0,
        "undelivered": 0,
        "responded": 0,
        "replied_stop": 0
      },
      {
        "id": "PxB9NV9YOy",
        "name": null,
        "message": "Iusto facere eius eligendi.",
        "media_url": null,
        "estimated_segments_sms": 1,
        "estimated_segments_mms": 0,
        "status_callback": null,
        "status": "draft",
        "created_at": 1781280064.469992,
        "updated_at": 1781280064.469992,
        "scheduled_for": 1781884864.469915,
        "completed_at": null,
        "user": {
          "email": "person_55@example.com",
          "id": "k5V9Vxz8lr",
          "name": "Person 39",
          "image_url": null,
          "signed_in_at": null,
          "avobot_id": null,
          "phone": null,
          "phone_formatted": null,
          "created_at": 1781280064.46497,
          "require_2fa": true,
          "mfa_app_valid": false,
          "phone_valid": false
        },
        "assign_to_user_id": null,
        "boost_multiplier": 1,
        "sms_errors": {},
        "mms_errors": {},
        "audience": 0,
        "contacts_count": 0,
        "attempted": 0,
        "delivered": 0,
        "undelivered": 0,
        "responded": 0,
        "replied_stop": 0
      }
    ]
  },
  "page": 1
}

List Broadcasts

Fetch a paginated list of broadcasts

Endpoint

GET /v1/broadcasts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
page Page number to request
created_at[from] Show Broadcasts created after this unix timestamp
created_at[to] Show Broadcasts created before this unix timestamp

Request

Route

GET /v1/broadcasts?auth_id=0nMJLyk8vZ&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=0nMJLyk8vZ
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/broadcasts?auth_id=0nMJLyk8vZ&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 5c4a00a8-606b-4e7d-9f0c-f0fac3dde3a8
X-Runtime: 0.023625
Content-Length: 1259

Body

{
  "status": 200,
  "data": {
    "broadcasts": [
      {
        "id": "0N6bwR8DML",
        "name": null,
        "message": "Officiis et sed rerum.",
        "media_url": null,
        "estimated_segments_sms": 1,
        "estimated_segments_mms": 0,
        "status_callback": null,
        "status": "draft",
        "created_at": 1781280065.034111,
        "updated_at": 1781280065.034111,
        "scheduled_for": 1781884865.034038,
        "completed_at": null,
        "user": {
          "email": "person_58@example.com",
          "id": "NEnJdnQbRm",
          "name": "Person 42",
          "image_url": null,
          "signed_in_at": null,
          "avobot_id": null,
          "phone": null,
          "phone_formatted": null,
          "created_at": 1781280065.02811,
          "require_2fa": true,
          "mfa_app_valid": false,
          "phone_valid": false
        },
        "assign_to_user_id": null,
        "boost_multiplier": 1
      },
      {
        "id": "qQR9178geK",
        "name": null,
        "message": "Incidunt aut eum porro.",
        "media_url": null,
        "estimated_segments_sms": 1,
        "estimated_segments_mms": 0,
        "status_callback": null,
        "status": "draft",
        "created_at": 1781280065.0329971,
        "updated_at": 1781280065.0329971,
        "scheduled_for": 1781884865.032707,
        "completed_at": null,
        "user": {
          "email": "person_58@example.com",
          "id": "NEnJdnQbRm",
          "name": "Person 42",
          "image_url": null,
          "signed_in_at": null,
          "avobot_id": null,
          "phone": null,
          "phone_formatted": null,
          "created_at": 1781280065.02811,
          "require_2fa": true,
          "mfa_app_valid": false,
          "phone_valid": false
        },
        "assign_to_user_id": null,
        "boost_multiplier": 1
      }
    ]
  },
  "page": 1,
  "limit": 30
}

Publish Broadcast

Publish your broadcast

Endpoint

POST /v1/broadcasts/:id/publish

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
scheduled_for Unix timestamp, Ensure delivery at this time
asap Boolean, Ignore schedule_for and schedule ASAP

Request

Route

POST /v1/broadcasts/BLP9Me9qYX/publish

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "BLP9MzeJqY",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "scheduled_for": 1781244064.769004,
  "asap": true
}

cURL

curl "https://www.avochato.com/v1/broadcasts/BLP9Me9qYX/publish" -d '{"auth_id":"BLP9MzeJqY","auth_secret":"YYYYYYYYYYYYYYYYYYYY","scheduled_for":1781244064.769004,"asap":true}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: f84f673f-5e40-4b13-b7d6-a4ff88e7917e
X-Runtime: 0.093066
Content-Length: 771

Body

{
  "status": 200,
  "data": {
    "broadcast": {
      "id": "BLP9Me9qYX",
      "name": null,
      "message": "Et in tenetur nam.",
      "media_url": null,
      "estimated_segments_sms": 1,
      "estimated_segments_mms": 0,
      "status_callback": null,
      "status": "draft",
      "created_at": 1781280064.6996942,
      "updated_at": 1781280064.6996942,
      "scheduled_for": 1781280074.800411,
      "completed_at": null,
      "user": {
        "email": "person_56@example.com",
        "id": "qxk9ELVbRK",
        "name": "Person 40",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280064.69349,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      },
      "assign_to_user_id": null,
      "boost_multiplier": 1,
      "sms_errors": {},
      "mms_errors": {},
      "audience": 1,
      "contacts_count": 1,
      "attempted": 0,
      "delivered": 0,
      "undelivered": 0,
      "responded": 0,
      "replied_stop": 0
    }
  }
}

Update Broadcast

Add more contacts or update your broadcast

Endpoint

POST /v1/broadcasts/:id

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
message String, the Message you want to broadcast (1600 character limit)
media_url Url of media to send in MMS (500kb limit)
name String, name of this broadcast
via_tags Comma-separated list of contact tags to add to this broadcast
via_contact_ids Comma-separated list of contact ids to add to this broadcast
via_phone_numbers Comma-separated list of phone_numbers to add to this broadcast
via_field[field] String, [:name, :phone, :phone_formatted, :email, :company, :street, :city, :state, :country, :zip, :priority, :opted_out, :salesforce_object_id, :salesforce_object_type], OR Custom Variable name
via_field[value] String, match all contacts with a given field which matches this value exactly

Request

Route

POST /v1/broadcasts/xDjJBRJoOe

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "enL8aAl87N",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "message": "new test message",
  "media_url": "https://somesite.com/pretty2.jpg",
  "name": "My Other Broadcast",
  "via_tags": "tag2,tag3",
  "via_contact_ids": "EZA9Pl59rw",
  "via_phone_numbers": "+15105551234,+14155551234",
  "via_field[field]": "email",
  "via_field[value]": "bob@mctest.com"
}

cURL

curl "https://www.avochato.com/v1/broadcasts/xDjJBRJoOe" -d '{"auth_id":"enL8aAl87N","auth_secret":"YYYYYYYYYYYYYYYYYYYY","message":"new test message","media_url":"https://somesite.com/pretty2.jpg","name":"My Other Broadcast","via_tags":"tag2,tag3","via_contact_ids":"EZA9Pl59rw","via_phone_numbers":"+15105551234,+14155551234","via_field[field]":"email","via_field[value]":"bob@mctest.com"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: e424c2f8-2ea5-4a2a-8593-e323a594c6a0
X-Runtime: 0.104855
Content-Length: 841

Body

{
  "status": 200,
  "data": {
    "broadcast": {
      "id": "xDjJBRJoOe",
      "name": "My Other Broadcast",
      "message": "new test message",
      "media_url": "https://somesite.com/pretty2.jpg",
      "estimated_segments_sms": 1,
      "estimated_segments_mms": 1,
      "status_callback": null,
      "status": "draft",
      "created_at": 1781280064.2500448,
      "updated_at": 1781280064.343262,
      "scheduled_for": 1781884864.249413,
      "completed_at": null,
      "user": {
        "email": "person_54@example.com",
        "id": "M3NbrBKbr6",
        "name": "Person 38",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280064.24406,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      },
      "assign_to_user_id": null,
      "boost_multiplier": 1,
      "sms_errors": {},
      "mms_errors": {},
      "audience": 1,
      "contacts_count": 1,
      "attempted": 0,
      "delivered": 0,
      "undelivered": 0,
      "responded": 0,
      "replied_stop": 0,
      "pending_contacts_count": 3
    }
  }
}

CallTokens

Create Call Token

Using your auth id + secret you can create a token to make a call

Endpoint

POST /v1/calls

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field

Request

Route

POST /v1/calls

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "wd6Jmz87m3",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/calls" -d '{"auth_id":"wd6Jmz87m3","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com" \
	-H "User-Agent: Test"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 51dd51ae-4f23-48c5-bc14-09b683607476
X-Runtime: 0.119466
Content-Length: 93

Body

{
  "status": 200,
  "data": {
    "twilio_token": null,
    "twilio_payload": {
      "account_hash_id": "wd6Jmz87m3"
    }
  }
}

Campaigns

Fetch Campaigns

Fetch a list of specific campaigns by their ids

Endpoint

GET /v1/campaigns/:ids

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of campaign keys to fetch
page Page to request

Request

Route

GET /v1/campaigns/one?auth_id=xDjJBnRJoO&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=xDjJBnRJoO
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/campaigns/one?auth_id=xDjJBnRJoO&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 0a904a7f-ff3f-4d0d-8b34-79ae0772c3d2
X-Runtime: 0.016513
Content-Length: 245

Body

{
  "status": 200,
  "data": {
    "campaigns": [
      {
        "id": "KRg80abj0q",
        "key": "one",
        "raw_text": "[Campaign 1] first message",
        "follow_up_message": "[Campaign 1] second message",
        "follow_up_delay": null,
        "media_url": null,
        "hash_id": "KRg80abj0q",
        "hotkey": null
      }
    ]
  },
  "page": 1
}

List Campaigns

List all campaign steps in this inbox.

Endpoint

GET /v1/campaigns

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field

Request

Route

GET /v1/campaigns?auth_id=ezjJ76L95y&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=ezjJ76L95y
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/campaigns?auth_id=ezjJ76L95y&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 114f864d-8836-4cbb-a520-72ae7598ba68
X-Runtime: 0.018362
Content-Length: 435

Body

{
  "status": 200,
  "data": {
    "campaigns": [
      {
        "id": "WAnJQmJy1v",
        "key": "one",
        "raw_text": "[Campaign 1] first message",
        "follow_up_message": "[Campaign 1] second message",
        "follow_up_delay": null,
        "media_url": null,
        "hash_id": "WAnJQmJy1v",
        "hotkey": null
      },
      {
        "id": "0nMJLk9vZ2",
        "key": "two",
        "raw_text": "[Campaign 2] first message",
        "follow_up_message": "[Campaign 2] second message",
        "follow_up_delay": null,
        "media_url": null,
        "hash_id": "0nMJLk9vZ2",
        "hotkey": null
      }
    ]
  }
}

Recursively remove a contact from a campaign

Remove a contact from a campaign and any subsequent steps in that campaign, using their phone number. Cancels any pending messages that would be sent by this campaign. If the contact has already started this campaign step, also cancels any pending messages from later campaign steps they may be currently on.

Endpoint

POST /v1/campaigns/:id/cancel

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Campaign keyword, or comma-separated list of campaign keywords.
phone required Phone number of the contact to cancel the campaign
recursive required (Boolean) Cancel this step as well as all subsequent steps in this campaign (1 or 0, defaults to 0).

Request

Route

POST /v1/campaigns/one/cancel

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "wd6Jmzz87m",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+15105551234",
  "recursive": "1"
}

cURL

curl "https://www.avochato.com/v1/campaigns/one/cancel" -d '{"auth_id":"wd6Jmzz87m","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+15105551234","recursive":"1"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a54b25ca-49f5-41c4-9ea7-774a23a6f2dc
X-Runtime: 0.029703
Content-Length: 107

Body

{
  "status": 200,
  "data": {
    "campaigns": "Processing 1 cancellations.",
    "contacts": [
      "+15105551234"
    ],
    "ids": [
      "one"
    ]
  }
}

Remove a contact from a campaign step

You can remove a contact from a campaign by their phone number. Cancels any pending messages that would be sent by this campaign.

Endpoint

POST /v1/campaigns/:id/cancel

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Campaign keyword, or comma-separated list of campaign keywords.
phone required Phone number of the contact to cancel the campaign

Request

Route

POST /v1/campaigns/one/cancel

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "v5D9R5bVAL",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+15105551234"
}

cURL

curl "https://www.avochato.com/v1/campaigns/one/cancel" -d '{"auth_id":"v5D9R5bVAL","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+15105551234"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a6de0fc0-222c-465d-8f5e-5e1ac3ea5900
X-Runtime: 0.054562
Content-Length: 107

Body

{
  "status": 200,
  "data": {
    "campaigns": "Processing 1 cancellations.",
    "contacts": [
      "+15105551234"
    ],
    "ids": [
      "one"
    ]
  }
}

Remove all contacts from a campaign step

Remove all contacts from a campaign. Cancels any pending messages that would be sent by this campaign.

Endpoint

POST /v1/campaigns/:id/cancel

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Campaign keyword, or comma-separated list of campaign keywords.
all required (Boolean) Cancel campaign for all contacts that are current on this step. Cannot pass "phone" or "contacts" when using this param. (1 or 0, defaults to 0)

Request

Route

POST /v1/campaigns/one/cancel

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "VePJl7Y9ar",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "all": "1"
}

cURL

curl "https://www.avochato.com/v1/campaigns/one/cancel" -d '{"auth_id":"VePJl7Y9ar","auth_secret":"YYYYYYYYYYYYYYYYYYYY","all":"1"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 639d2f41-70b6-4c2c-9ddf-805e868ea936
X-Runtime: 0.039898
Content-Length: 147

Body

{
  "status": 200,
  "data": {
    "campaigns": "Processing cancellation of all contacts from 1 campaigns. This may take a moment.",
    "contacts": [],
    "ids": [
      "one"
    ]
  }
}

Remove multiple contacts from a campaign step

Remove contacts from a campaign step by their phone numbers. Cancels any pending messages that would be sent by this campaign to any of the contacts, if they are currently part of the campaign.

Endpoint

POST /v1/campaigns/:id/cancel

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Campaign keyword, or comma-separated list of campaign keywords.
contacts required List of contacts to cancel

Request

Route

POST /v1/campaigns/one/cancel

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "ZMvbX0zbRm",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "contacts": [
    "+15105551234",
    "+15551234568"
  ]
}

cURL

curl "https://www.avochato.com/v1/campaigns/one/cancel" -d '{"auth_id":"ZMvbX0zbRm","auth_secret":"YYYYYYYYYYYYYYYYYYYY","contacts":["+15105551234","+15551234568"]}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 3c13fe13-658e-40b2-a48e-e8e326b7eb8c
X-Runtime: 0.061314
Content-Length: 128

Body

{
  "status": 200,
  "data": {
    "campaigns": "Processing up to 2 cancellations.",
    "contacts": [
      "+15105551234",
      "+15551234568"
    ],
    "ids": [
      "one"
    ]
  }
}

Contacts

Fetch Contacts

Retrieve a specific Contact (or Contacts) using one or more comma-separated ids

Endpoint

GET /v1/contacts/:ids

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of Contact ids to fetch
page Page to request

Request

Route

GET /v1/contacts/2jRbk681Pv%2CenL8alJ7Nw?auth_id=xDjJBRJoOe&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=xDjJBRJoOe
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/contacts/2jRbk681Pv%2CenL8alJ7Nw?auth_id=xDjJBRJoOe&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 27808e3b-61c0-41ce-bd2d-38042d7e2f17
X-Runtime: 0.118862
Content-Length: 1202

Body

{
  "status": 200,
  "data": {
    "contacts": [
      {
        "id": "2jRbk681Pv",
        "name": "Bob McTest",
        "phone": "+15551234567",
        "email": "bob@mctest.com",
        "street": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "99999",
        "country": "US",
        "address": "Los Angeles, CA, 99999, US",
        "notes": null,
        "company": "McTest Inc",
        "other_phone": null,
        "created_at": 1781279453.82907,
        "tags": [
          "important"
        ],
        "tag_details": [
          {
            "name": "important",
            "color": null,
            "duration": null,
            "routable": null
          }
        ],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      },
      {
        "id": "enL8alJ7Nw",
        "name": "Other Contact",
        "phone": "+15551234568",
        "email": "bob@contact.com",
        "street": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "88888",
        "country": "US",
        "address": "San Francisco, CA, 88888, US",
        "notes": null,
        "company": "Contact Inc",
        "other_phone": null,
        "created_at": 1781280053.83647,
        "tags": [],
        "tag_details": [],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      }
    ]
  },
  "page": 1
}

List All Contacts

Returns a paginated list of Contacts in this inbox

Endpoint

GET /v1/contacts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
after_page Timestamp, return records created after this Unix timestamp, in milliseconds
limit Integer, number of records to return (default: 25, max: 100)

Request

Route

GET /v1/contacts?auth_id=2jRbk681Pv&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=2jRbk681Pv
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/contacts?auth_id=2jRbk681Pv&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 613eece5-0b70-435c-886d-9e8a2baa5e74
X-Runtime: 0.076538
Content-Length: 1163

Body

{
  "status": 200,
  "data": {
    "contacts": [
      {
        "id": "PxB9NV9YOy",
        "name": "Bob McTest",
        "phone": "+15551234567",
        "email": "bob@mctest.com",
        "street": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "99999",
        "country": "US",
        "address": "Los Angeles, CA, 99999, US",
        "notes": null,
        "company": "McTest Inc",
        "other_phone": null,
        "created_at": 1781279454.08314,
        "tags": [],
        "tag_details": [],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      },
      {
        "id": "BLP9Me9qYX",
        "name": "Other Contact",
        "phone": "+15551234568",
        "email": "bob@contact.com",
        "street": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "88888",
        "country": "US",
        "address": "San Francisco, CA, 88888, US",
        "notes": null,
        "company": "Contact Inc",
        "other_phone": null,
        "created_at": 1781280054.09281,
        "tags": [],
        "tag_details": [],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      }
    ],
    "size": 2,
    "next_page": null
  },
  "page": 1,
  "limit": 30
}

Paginate contact results

Search for matching Contacts based on a query string

Endpoint

GET /v1/contacts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
query String to search Contacts with (default: iterate through all Contacts)
after_page Show the next set of contacts that match this search, created after this unixtime. Used for pagination.
limit Integer, number of records to return (default: 25, max: 100)
visible Boolean, show only visible contacts (defaults to true, set to false to include deleted contacts)

Request

Route

GET /v1/contacts?auth_id=PxB9NV9YOy&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=country%3AUS&after_page=eW3xEK1QelN

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=PxB9NV9YOy
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=country:US
after_page=eW3xEK1QelN

cURL

curl -g "https://www.avochato.com/v1/contacts?auth_id=PxB9NV9YOy&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=country%3AUS&after_page=eW3xEK1QelN" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 7c26c24e-9ca1-47fb-81b8-aac7e1a91e5a
X-Runtime: 0.066298
Content-Length: 644

Body

{
  "status": 200,
  "data": {
    "contacts": [
      {
        "id": "0N6bwR8DML",
        "name": "Other Contact",
        "phone": "+15551234568",
        "email": "bob@contact.com",
        "street": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "88888",
        "country": "US",
        "address": "San Francisco, CA, 88888, US",
        "notes": null,
        "company": "Contact Inc",
        "other_phone": null,
        "created_at": 1781280054.5899,
        "tags": [],
        "tag_details": [],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      }
    ],
    "size": 1,
    "next_page": null
  },
  "limit": 30,
  "after_page": "eW3xEK1QelN"
}

Remove all contacts

Remove all contacts from this inbox.

Endpoint

DELETE /v1/contacts/remove_all

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
query String. If query is empty or no query parameter is provided, remove *all* contacts from the contacts list in this inbox. If a query is provided, only contacts matching the query will be removed from this inbox.

Request

Route

DELETE /v1/contacts/remove_all

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "BLP9Me9qYX",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "query": null
}

cURL

curl "https://www.avochato.com/v1/contacts/remove_all" -d '{"auth_id":"BLP9Me9qYX","auth_secret":"YYYYYYYYYYYYYYYYYYYY","query":null}' -X DELETE \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: acb356fd-64b7-4d8b-8568-5570a4d908da
X-Runtime: 0.021439
Content-Length: 57

Body

{
  "status": 200,
  "data": {
    "account": "account_8",
    "query": "*"
  }
}

Search Contacts

Search for matching Contacts based on a query string

Endpoint

GET /v1/contacts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
query String to search Contacts with (default: iterate through all Contacts)
created_at[from] Select Contacts created after this unixtime
created_at[to] Select Contacts created before this unixtime (default: now)
after_page String, Show results created after this ID. Used for pagination.
limit Integer, number of records to return (default: 25, max: 100)
visible Boolean, show only visible contacts (defaults to true, set to false to include deleted contacts)

Request

Route

GET /v1/contacts?auth_id=0nMJLk9vZ2&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=name%3ABob+OR+city%3A%22San+Francisco%22&created_at%5Bfrom%5D=1781279395.495039&created_at%5Bto%5D=1781279515.495054

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=0nMJLk9vZ2
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=name:Bob OR city:"San Francisco"
created_at={"from" => "1781279395.495039", "to" => "1781279515.495054"}

cURL

curl -g "https://www.avochato.com/v1/contacts?auth_id=0nMJLk9vZ2&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=name%3ABob+OR+city%3A%22San+Francisco%22&created_at%5Bfrom%5D=1781279395.495039&created_at%5Bto%5D=1781279515.495054" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 5a0c592e-f7c8-458c-b91c-a2074933dd52
X-Runtime: 0.053908
Content-Length: 618

Body

{
  "status": 200,
  "data": {
    "contacts": [
      {
        "id": "AwebYoJaEr",
        "name": "Bob McTest",
        "phone": "+15551234567",
        "email": "bob@mctest.com",
        "street": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "99999",
        "country": "US",
        "address": "Los Angeles, CA, 99999, US",
        "notes": null,
        "company": "McTest Inc",
        "other_phone": null,
        "created_at": 1781279455.44648,
        "tags": [],
        "tag_details": [],
        "opted_out": false,
        "double_opted_in": false,
        "muted": false,
        "blocked": false,
        "salesforce_object_type": null,
        "salesforce_object_id": null,
        "priority": 0,
        "user_id": null,
        "visible": true,
        "current_owner": null,
        "due_for_compliance": true
      }
    ],
    "size": 1,
    "next_page": null
  },
  "page": 1,
  "limit": 30
}

Update Multiple Contacts

Create or update multiple Contacts based on their phone numbers. Given a list of contacts, Avochato will attempt to update or create a record for each unique contact, based on their phone number.

Endpoint

POST /v1/contacts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
contacts required List of Contacts
contacts[n][phone] required Phone number of Contact
contacts[n][name] Name of the Contact
contacts[n][email] Email for the Contact
contacts[n][other_phone] Other phone for the Contact
contacts[n][company] Company Name for the Contact
contacts[n][street] Street for the Contact
contacts[n][city] City for the Contact
contacts[n][state] State for the Contact
contacts[n][zip] Zip Code for the Contact
contacts[n][country] Country for the Contact
contacts[n][opted_out] Opted-out status of the Contact. Avochato will prevent any outbound message to an opted out contact.
contacts[n][double_opted_in] Boolean, 0 or 1. Update the Double Opt-in status of the contact.
contacts[n][muted] Boolean, 0 or 1. Mute or unmute the Contact to suppress calls and notifications from them.
contacts[n][blocked] Boolean, 0 or 1. Block or unblock the Contact to prevent all calls and texts to and from them.
contacts[n][priority] Integer, 0 through 5. Sets a priority level for the contact, 5 is the greatest.
contacts[n][visible] Boolean, 0 or 1. Visibility status of the Contact. Set to 0 to remove the contact.
contacts[n][landline] Boolean, 0 or 1. Landline status of the Contact. Set to 1 to prevent SMS to this contact.
contacts[n][custom_variable_name] Custom field to set for the Contact
contacts[n][tags] CSV of tags to apply to the Contact
contacts[n][user_id] User ID or Email of a User that is responsible for this contact. Assigns all conversations to the user when set.
contacts[n][salesforce_object_id] Salesforce object id
contacts[n][salesforce_object_type] Salesforce object type
contacts[n][stuck_number] Send all future outbounds using this Avochato number (E.164 format, number must belong to this account)
allow_empty_fields Boolean, 0 or 1. Permit overwriting custom fields with empty or null value (defaults to 0)

Request

Route

POST /v1/contacts

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "WAnJQmJy1v",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "contacts": [
    {
      "phone": "+14155553333",
      "name": "Bob McTest",
      "email": "contact@example.com",
      "company": "Example Inc.",
      "street": "123 Main St.",
      "city": "SF",
      "state": "CA",
      "zip": "99999",
      "country": "USA",
      "opted_out": false,
      "visible": true,
      "landline": false,
      "custom_variable_name": "value to set custom variable",
      "tags": "red,green,blue",
      "user_id": "teammate@example.com",
      "salesforce_object_id": "0030030000000014cAAA",
      "salesforce_object_type": "Contact"
    }
  ]
}

cURL

curl "https://www.avochato.com/v1/contacts" -d '{"auth_id":"WAnJQmJy1v","auth_secret":"YYYYYYYYYYYYYYYYYYYY","contacts":[{"phone":"+14155553333","name":"Bob McTest","email":"contact@example.com","company":"Example Inc.","street":"123 Main St.","city":"SF","state":"CA","zip":"99999","country":"USA","opted_out":false,"visible":true,"landline":false,"custom_variable_name":"value to set custom variable","tags":"red,green,blue","user_id":"teammate@example.com","salesforce_object_id":"0030030000000014cAAA","salesforce_object_type":"Contact"}]}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: dc5c9e9a-be3f-4d14-ac32-7015222ffa04
X-Runtime: 0.470915
Content-Length: 882

Body

{
  "status": 200,
  "data": {
    "contact": {
      "id": "NEnJdQ8RmO",
      "name": "Bob McTest",
      "phone": "+14155553333",
      "email": "contact@example.com",
      "street": "123 Main St.",
      "city": "SF",
      "state": "CA",
      "zip": "99999",
      "country": "USA",
      "address": "123 Main St., SF, CA, 99999, USA",
      "notes": null,
      "company": "Example Inc.",
      "other_phone": null,
      "created_at": 1781280054.90916,
      "tags": [
        "red",
        "green",
        "blue"
      ],
      "tag_details": [
        {
          "name": "red",
          "color": null,
          "duration": null,
          "routable": false
        },
        {
          "name": "green",
          "color": null,
          "duration": null,
          "routable": false
        },
        {
          "name": "blue",
          "color": null,
          "duration": null,
          "routable": false
        }
      ],
      "opted_out": false,
      "double_opted_in": false,
      "muted": false,
      "blocked": false,
      "salesforce_object_type": "Contact",
      "salesforce_object_id": "0030030000000014cAAA",
      "priority": 0,
      "user_id": "0nMJLk9vZ2",
      "visible": true,
      "current_owner": "0nMJLk9vZ2",
      "due_for_compliance": true,
      "custom_variable_name": "value to set custom variable"
    }
  }
}

Update Single Contact

Create or update a single Contact based on their phone number.

Endpoint

POST /v1/contacts

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number of Contact
name Name of the Contact
email Email for the Contact
other_phone Other phone for the Contact
company Company Name for the Contact
street Street for the Contact
city City for the Contact
state State for the Contact
zip Zip Code for the Contact
country Country for the Contact
opted_out Opted-out status of the Contact. Avochato will prevent any outbound message to an opted out contact.
double_opted_in Boolean, 0 or 1. Update the Double Opt-in status of the contact.
muted Boolean, 0 or 1. Mute or unmute the Contact to suppress calls and notifications from them.
blocked Boolean, 0 or 1. Block or unblock the Contact to prevent all calls and texts to and from them.
priority Integer, 0 through 5. Sets a priority level for the contact, 5 is the greatest.
visible Boolean, 0 or 1. Visibility status of the Contact. Set to 0 to remove the contact.
landline Boolean, 0 or 1. Landline status of the Contact. Set to 1 to prevent SMS to this contact.
custom_variable_name Custom variable to set for the Contact
tags CSV of tags to apply to the Contact
user_id User ID or Email of a User that is responsible for this contact. Assigns all conversations to the user when set.
salesforce_object_id Salesforce object id
salesforce_object_type Salesforce object type
allow_empty_fields Boolean, 0 or 1. Permit overwriting custom fields with empty or null value (defaults to 0)
stuck_number Send all future outbounds using this Avochato number (E.164 format, number must belong to this account)

Request

Route

POST /v1/contacts

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "enL8alJ7Nw",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+14155553333",
  "name": "Bob McTest",
  "email": "contact@example.com",
  "company": "Example Inc.",
  "street": "123 Main St.",
  "city": "SF",
  "state": "CA",
  "zip": "99999",
  "country": "USA",
  "opted_out": false,
  "visible": true,
  "landline": false,
  "custom_variable_name": "value to set custom variable",
  "tags": "red,green,blue",
  "user_id": "teammate@example.com",
  "salesforce_object_id": "0030030000000014cAAA",
  "salesforce_object_type": "Contact",
  "stuck_number": ""
}

cURL

curl "https://www.avochato.com/v1/contacts" -d '{"auth_id":"enL8alJ7Nw","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+14155553333","name":"Bob McTest","email":"contact@example.com","company":"Example Inc.","street":"123 Main St.","city":"SF","state":"CA","zip":"99999","country":"USA","opted_out":false,"visible":true,"landline":false,"custom_variable_name":"value to set custom variable","tags":"red,green,blue","user_id":"teammate@example.com","salesforce_object_id":"0030030000000014cAAA","salesforce_object_type":"Contact","stuck_number":""}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 46a15093-28f5-4b63-8643-b314b060c765
X-Runtime: 0.176629
Content-Length: 658

Body

{
  "status": 200,
  "data": {
    "contact": {
      "id": "KRg80abj0q",
      "name": "Bob McTest",
      "phone": "+14155553333",
      "email": "contact@example.com",
      "street": "123 Main St.",
      "city": "SF",
      "state": "CA",
      "zip": "99999",
      "country": "USA",
      "address": "123 Main St., SF, CA, 99999, USA",
      "notes": null,
      "company": "Example Inc.",
      "other_phone": null,
      "created_at": 1781280054.44,
      "tags": [],
      "tag_details": [],
      "opted_out": false,
      "double_opted_in": false,
      "muted": false,
      "blocked": false,
      "salesforce_object_type": "Contact",
      "salesforce_object_id": "0030030000000014cAAA",
      "priority": 0,
      "user_id": null,
      "visible": true,
      "current_owner": null,
      "due_for_compliance": true,
      "custom_variable_name": "value to set custom variable"
    }
  }
}

Events

Add Event (Contact id)

Using your auth id + secret you can append an Event directly into a Conversation stream based on the Contact id

Endpoint

POST /v1/contacts/:id/events

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Contact id to add an event to
type required Type of event to log: click, sale, etc.
context Context to save regarding the event
revenue Value created for your team from this event

Request

Route

POST /v1/contacts/RkAJvDlb0o/events

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "xoWbqYbqnB",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "type": "sale",
  "context": "Wanted a new watch ($99.99) with no warranty",
  "revenue": 99.99
}

cURL

curl "https://www.avochato.com/v1/contacts/RkAJvDlb0o/events" -d '{"auth_id":"xoWbqYbqnB","auth_secret":"YYYYYYYYYYYYYYYYYYYY","type":"sale","context":"Wanted a new watch ($99.99) with no warranty","revenue":99.99}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 1e49cf7d-10d8-4661-9d26-004b6720bc8e
X-Runtime: 0.089988
Content-Length: 347

Body

{
  "status": 200,
  "data": {
    "event": {
      "user_id": "ezjJ76L95y",
      "account_id": "xlYJpq8mwM",
      "ticket_id": "WAnJQLm9y1",
      "contact_id": "RkAJvDlb0o",
      "qa_keyword_id": null,
      "type": "sale",
      "context": "Wanted a new watch ($99.99) with no warranty",
      "revenue": 99.99,
      "event_id": "WAnJQLm9y1",
      "element_id": "wd6Jmz87m3",
      "element_type": "CustomEvent",
      "sent_at": 1781280062.21448
    }
  }
}

Add Event (Phone)

Using your auth id + secret you can append an Event directly into a Conversation stream based on the phone number

Endpoint

POST /v1/events

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number of the Contact
type required Type of event to log: click, sale, etc.
context Context to save regarding the event
revenue Value created for your team from this event

Request

Route

POST /v1/events

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "43y83xbVNM",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+15551234567",
  "type": "sale",
  "context": "Bought an avocado ($2) and was interested in a subscription",
  "revenue": 2.0
}

cURL

curl "https://www.avochato.com/v1/events" -d '{"auth_id":"43y83xbVNM","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+15551234567","type":"sale","context":"Bought an avocado ($2) and was interested in a subscription","revenue":2.0}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 5aa2a61f-a16a-44ee-a9f3-fb9948a29f77
X-Runtime: 0.052017
Content-Length: 360

Body

{
  "status": 200,
  "data": {
    "event": {
      "user_id": "xDjJBnRJoO",
      "account_id": "v5D9R5bVAL",
      "ticket_id": "0nMJLyk8vZ",
      "contact_id": "3Ynbgne8ae",
      "qa_keyword_id": null,
      "type": "sale",
      "context": "Bought an avocado ($2) and was interested in a subscription",
      "revenue": 2.0,
      "event_id": "kvnJA1eJAD",
      "element_id": "VePJlY8ar6",
      "element_type": "CustomEvent",
      "sent_at": 1781280062.38156
    }
  }
}

Add Event (Ticket id)

Using your auth id + secret you can append an Event directly into a Conversation stream based on the Ticket id

Endpoint

POST /v1/tickets/:id/events

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL) Ticket id to add event to
type required Type of event to log: click, sale, etc.
context Context to save regarding the event
revenue Value created for your team from this event

Request

Route

POST /v1/tickets/qQR91D7bge/events

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "xlYJpq8mwM",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "type": "sale",
  "context": "Wanted one hat ($10) and upsold warranty ($5.50)",
  "revenue": 15.5
}

cURL

curl "https://www.avochato.com/v1/tickets/qQR91D7bge/events" -d '{"auth_id":"xlYJpq8mwM","auth_secret":"YYYYYYYYYYYYYYYYYYYY","type":"sale","context":"Wanted one hat ($10) and upsold warranty ($5.50)","revenue":15.5}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 1ae8d03f-89e9-4e66-99a1-017b4190cbaf
X-Runtime: 0.021343
Content-Length: 350

Body

{
  "status": 200,
  "data": {
    "event": {
      "user_id": "enL8aAl87N",
      "account_id": "wd6Jmzz87m",
      "ticket_id": "qQR91D7bge",
      "contact_id": "PDz9nV29e3",
      "qa_keyword_id": null,
      "type": "sale",
      "context": "Wanted one hat ($10) and upsold warranty ($5.50)",
      "revenue": 15.5,
      "event_id": "3OLb4WY84Y",
      "element_id": "ezjJ7L85yZ",
      "element_type": "CustomEvent",
      "sent_at": 1781280062.65373
    }
  }
}

Fetch Events

Using your auth id + secret you can fetch Events in a Ticket based on Ticket ids

Endpoint

GET /v1/tickets/:ids/events

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Ticket ids to fetch the event stream
page Page to request

Request

Route

GET /v1/tickets/KRg80KaJj0/events?auth_id=wEG8j28QlW&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=wEG8j28QlW
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/tickets/KRg80KaJj0/events?auth_id=wEG8j28QlW&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: ea0b0375-63b3-4432-8b18-2a8ab937a7dd
X-Runtime: 0.047664
Content-Length: 2852

Body

{
  "status": 200,
  "data": {
    "events": [
      {
        "account_id": "ZMvbX0zbRm",
        "ticket_id": "KRg80KaJj0",
        "user_id": "2jRbkR681P",
        "status": "Closed",
        "event_id": "3o48OvgJeA",
        "element_id": "BLP9Me9qYX",
        "element_type": "StatusChange",
        "sent_at": 1781280062.48186
      },
      {
        "account_id": "ZMvbX0zbRm",
        "call_from": "+15551234567",
        "call_to": "+15558888888",
        "voicemail": null,
        "direction": "in",
        "call_status": "completed",
        "ended_at": 0.0,
        "duration": 119,
        "segments": 2,
        "recording_url": null,
        "recording_status": null,
        "transcript": null,
        "transcript_status": null,
        "summary": null,
        "event_id": "PDz9nV29e3",
        "element_id": "enL8alJ7Nw",
        "element_type": "Call",
        "sent_at": 1781280062.48011
      },
      {
        "uuid": "52f43ce2-048b-4dd5-8bf8-9356df05a22a",
        "account_id": "ZMvbX0zbRm",
        "ticket_id": "KRg80KaJj0",
        "contact_id": "1LxJDvKbn2",
        "sender_id": "2jRbkR681P",
        "sender_type": "User",
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": null,
        "from": null,
        "direction": "out",
        "origin": null,
        "message": "Sorry in a meeting but can call afterwards",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "queued",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781280062.4768,
        "sent_at": 1781280062.47776,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "1LxJDvKbn2",
        "element_id": "1K2b2vbWRy",
        "element_type": "SmsMessage"
      },
      {
        "uuid": "372000cd-39fb-4474-87d9-c81239925c0e",
        "account_id": "ZMvbX0zbRm",
        "ticket_id": "KRg80KaJj0",
        "contact_id": "1LxJDvKbn2",
        "sender_id": "2jRbkR681P",
        "sender_type": "User",
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": null,
        "from": null,
        "direction": "out",
        "origin": null,
        "message": "Hey there Bob let me know when we can talk!",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "queued",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781280062.47425,
        "sent_at": 1781280062.47518,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "3Ynbgne8ae",
        "element_id": "EDR8z49A2k",
        "element_type": "SmsMessage"
      },
      {
        "account_id": "ZMvbX0zbRm",
        "call_from": "+15558888888",
        "call_to": "+15551234567",
        "voicemail": null,
        "direction": "out",
        "call_status": "completed",
        "ended_at": 0.0,
        "duration": 10,
        "segments": 1,
        "recording_url": null,
        "recording_status": null,
        "transcript": null,
        "transcript_status": null,
        "summary": null,
        "event_id": "RkAJvDlb0o",
        "element_id": "2jRbk681Pv",
        "element_type": "Call",
        "sent_at": 1781280062.47243
      },
      {
        "account_id": "ZMvbX0zbRm",
        "ticket_id": "KRg80KaJj0",
        "user_id": "2jRbkR681P",
        "status": "Open",
        "event_id": "AwebYqobaE",
        "element_id": "PxB9NV9YOy",
        "element_type": "StatusChange",
        "sent_at": 1781280062.46687
      },
      {
        "account_id": "ZMvbX0zbRm",
        "ticket_id": "KRg80KaJj0",
        "user_id": "2jRbkR681P",
        "owner_id": "2jRbkR681P",
        "old_owner_id": null,
        "event_id": "NEnJdnQbRm",
        "element_id": "0nMJLk9vZ2",
        "element_type": "OwnerChange",
        "sent_at": 1781280062.46291
      }
    ]
  },
  "page": 1,
  "limit": 30
}

Messages

Cancel Scheduled Message

Cancels a scheduled message from sending. Only applies to scheduled messages which have not yet been delivered.

Endpoint

DELETE /v1/messages/:id

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required Event ID of the scheduled message string

Request

Route

DELETE /v1/messages/43y83xbVNM

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "EDR8z49A2k",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/messages/43y83xbVNM" -d '{"auth_id":"EDR8z49A2k","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X DELETE \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 71f51340-5119-474a-ad31-584d39565a81
X-Runtime: 0.042862
Content-Length: 541

Body

{
  "status": 200,
  "data": {
    "message": {
      "account_id": "EDR8z49A2k",
      "ticket_id": "xDjJBnRJoO",
      "contact_id": "k5V9Vxz8lr",
      "sender": "person_36",
      "message": "Just wanted to follow up.",
      "media_url": null,
      "aborted": true,
      "sent": {
        "element_id": null,
        "element_type": null
      },
      "scheduled_for": 1781283660.4721642,
      "created_at": 1781279460.47216,
      "cancel_on": null,
      "aborter_id": 36,
      "aborted_by": "Test User",
      "abort_reason": "manually cancelled",
      "status_callback": null,
      "event_id": "43y83xbVNM",
      "element_id": "KRg80abj0q",
      "element_type": "PendingMessage",
      "sent_at": 1781280060.47576
    }
  }
}

Get Message

Retrieve an individual message by its corresponding Event ID

Endpoint

GET /v1/messages/:id

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required Event ID of the message string

Request

Route

GET /v1/messages/EZA9P5Jrwg?auth_id=z1N8x2937L&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=z1N8x2937L
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/messages/EZA9P5Jrwg?auth_id=z1N8x2937L&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a7e91c0e-551c-4ffa-9905-7da904b565cd
X-Runtime: 0.020319
Content-Length: 751

Body

{
  "status": 200,
  "data": {
    "message": {
      "uuid": "66775f5a-d8c3-486d-9c0d-74c1117b020e",
      "account_id": "z1N8x2937L",
      "ticket_id": "ZMvbX0zbRm",
      "contact_id": "KRg80KaJj0",
      "sender_id": null,
      "sender_type": null,
      "broadcast_id": null,
      "salesforce_activity_id": null,
      "salesforce_group_activity_id": null,
      "to": "+14155551234",
      "from": "+15105551234",
      "direction": "in",
      "origin": null,
      "message": "I kept hearing that you had great service 😀!",
      "contents": [],
      "segments": 1,
      "carrier": null,
      "external_id": null,
      "status": "delivered",
      "error_code": 0,
      "error_description": null,
      "reason": null,
      "status_callback": null,
      "created_at": 1781280060.10862,
      "sent_at": 1781280060.10997,
      "content_blocked": null,
      "boost_multiplier": 1,
      "event_id": "EZA9P5Jrwg",
      "element_id": "kvnJAeJADM",
      "element_type": "SmsMessage"
    }
  }
}

List All Messages

Returns a paginated list of Messages in this inbox

Endpoint

GET /v1/messages

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
page Page to request

Request

Route

GET /v1/messages?auth_id=BDr8Gk8PlQ&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=BDr8Gk8PlQ
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/messages?auth_id=BDr8Gk8PlQ&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 4c41a6f0-9b71-439b-950e-84fb77d03ccf
X-Runtime: 0.035593
Content-Length: 1460

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "uuid": "e0e18502-48cd-4271-8e7b-7470bb98424a",
        "account_id": "BDr8Gk8PlQ",
        "ticket_id": "VePJl7Y9ar",
        "contact_id": "0N6bwZR8DM",
        "sender_id": null,
        "sender_type": null,
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": "+14155551234",
        "from": "+15105551234",
        "direction": "in",
        "origin": null,
        "message": "I kept hearing that you had great service 😀!",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "delivered",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781280060.30081,
        "sent_at": 1781280060.30182,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "zPG9yg8aO0",
        "element_id": "AwebYoJaEr",
        "element_type": "SmsMessage"
      },
      {
        "uuid": "9d48841a-69e9-47af-9b24-fafc1985007a",
        "account_id": "BDr8Gk8PlQ",
        "ticket_id": "VePJl7Y9ar",
        "contact_id": "0N6bwZR8DM",
        "sender_id": null,
        "sender_type": null,
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": "+14155551234",
        "from": "+15105551234",
        "direction": "out",
        "origin": null,
        "message": "How did you hear about us?",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "delivered",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781279460.29591,
        "sent_at": 1781280060.2986,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "AEgb5r9ejL",
        "element_id": "NEnJdQ8RmO",
        "element_type": "SmsMessage"
      }
    ]
  },
  "page": 1
}

Search Messages

Search for matching Messages in an account based on a query.

Endpoint

GET /v1/messages

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
query Query to search Messages (default: iterate through all messages) string
page Page to request (default: 1) integer
direction Direction of the message ("in" for received messages, "out" for sent messages) string
status Message delivery status (ie: queued, delivered, undelivered, failed) string
from Phone number message was sent from string
to Phone number message was sent to string
contact_id Contact ID, filter messages sent or received by this Contact string
ticket_id Ticket ID, filter messages only within this Ticket string
sender_id User ID who sent this message, filter messages sent by this User string
created_at[from] Select messages created after this date unix_timestamp
created_at[to] Select messages created before this date (default: now) unix_timestamp

Request

Route

GET /v1/messages?auth_id=3YnbgeJae2&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=hear&page=1&direction=in&status=delivered&from=%2B15105551234&to=%2B14155551234&created_at%5Bfrom%5D=1781274058.9103732&created_at%5Bto%5D=1781280118.91039

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=3YnbgeJae2
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=hear
page=1
direction=in
status=delivered
from=+15105551234
to=+14155551234
created_at={"from" => "1781274058.9103732", "to" => "1781280118.91039"}

cURL

curl -g "https://www.avochato.com/v1/messages?auth_id=3YnbgeJae2&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=hear&page=1&direction=in&status=delivered&from=%2B15105551234&to=%2B14155551234&created_at%5Bfrom%5D=1781274058.9103732&created_at%5Bto%5D=1781280118.91039" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: daf53be4-7865-407e-beeb-d150392a3056
X-Runtime: 0.070723
Content-Length: 763

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "uuid": "ef979f8c-bb21-457c-8b50-bcf29a39632b",
        "account_id": "3YnbgeJae2",
        "ticket_id": "Pe6bez9Xwy",
        "contact_id": "xlYJpq8mwM",
        "sender_id": null,
        "sender_type": null,
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": "+14155551234",
        "from": "+15105551234",
        "direction": "in",
        "origin": null,
        "message": "I kept hearing that you had great service 😀!",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "delivered",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781280058.73026,
        "sent_at": 1781280058.73121,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "M3NbrK9r6q",
        "element_id": "xDjJBRJoOe",
        "element_type": "SmsMessage"
      }
    ]
  },
  "page": 1
}

Search Messages by timestamp

Search for matching Messages sent between a time range.

Endpoint

GET /v1/messages

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
query Query to search Messages (default: iterate through all messages) string
page Page to request (default: 1) integer
direction Direction of the message ("in" for received messages, "out" for sent messages) string
status Message delivery status (ie: queued, delivered, undelivered, failed) string
from Phone number message was sent from string
to Phone number message was sent to string
contact_id Contact ID, filter messages sent or received by this Contact string
ticket_id Ticket ID, filter messages only within this Ticket string
sender_id User ID who sent this message, filter messages sent by this User string
created_at[from] Select messages created after this date unix_timestamp
created_at[to] Select messages created before this date (default: now) unix_timestamp

Request

Route

GET /v1/messages?auth_id=1LxJDK9n26&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=hear&page=1&direction&status=delivered&from=%2B15105551234&to=%2B14155551234&created_at%5Bfrom%5D=1781279999.1014452&created_at%5Bto%5D=1781280119.10146&document=false

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=1LxJDK9n26
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=hear
page=1
direction=
status=delivered
from=+15105551234
to=+14155551234
created_at={"from" => "1781279999.1014452", "to" => "1781280119.10146"}
document=false

cURL

curl -g "https://www.avochato.com/v1/messages?auth_id=1LxJDK9n26&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=hear&page=1&direction&status=delivered&from=%2B15105551234&to=%2B14155551234&created_at%5Bfrom%5D=1781279999.1014452&created_at%5Bto%5D=1781280119.10146&document=false" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 56f7e542-e828-4961-9503-ae6587ecc273
X-Runtime: 0.023158
Content-Length: 763

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "uuid": "c7c236fe-982b-403a-86ae-f8650e3cb52e",
        "account_id": "1LxJDK9n26",
        "ticket_id": "EZA9P5Jrwg",
        "contact_id": "ZMvbX0zbRm",
        "sender_id": null,
        "sender_type": null,
        "broadcast_id": null,
        "salesforce_activity_id": null,
        "salesforce_group_activity_id": null,
        "to": "+14155551234",
        "from": "+15105551234",
        "direction": "in",
        "origin": null,
        "message": "I kept hearing that you had great service 😀!",
        "contents": [],
        "segments": 1,
        "carrier": null,
        "external_id": null,
        "status": "delivered",
        "error_code": 0,
        "error_description": null,
        "reason": null,
        "status_callback": null,
        "created_at": 1781280059.06265,
        "sent_at": 1781280059.06378,
        "content_blocked": null,
        "boost_multiplier": 1,
        "event_id": "kvnJAeJADM",
        "element_id": "enL8alJ7Nw",
        "element_type": "SmsMessage"
      }
    ]
  },
  "page": 1
}

Search Scheduled Messages

Search for matching Messages scheduled in the future in an account based on a query. Includes future campaign follow up messages, individual scheduled messages, and delayed auto-responses. Does NOT include Broadcast messages.

Endpoint

GET /v1/messages/scheduled

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
query Query to search Messages (default: iterate through all scheduled messages) string
page Page to request (default: 1) integer
from Phone number message will be sent from string
to Phone number message will be sent to string
contact_id Contact ID, filter messages scheduled to send to this Contact string
ticket_id Ticket ID, filter messages scheduled within this Ticket string
sender_id User ID who sent this message, filter messages scheduled by this User string
scheduled_for[from] Select messages scheduled to send after this date (default: now) unix_timestamp
scheduled_for[to] Select messages scheduled to send before this date (default: one year from now) unix_timestamp
created_at[from] Select scheduled messages created after this date unix_timestamp
created_at[to] Select scheduled messages created before this date (default: now) unix_timestamp

Request

Route

GET /v1/messages/scheduled?auth_id=PDz9n29e3m&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=PDz9n29e3m
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=
page=1

cURL

curl -g "https://www.avochato.com/v1/messages/scheduled?auth_id=PDz9n29e3m&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 94c39e51-fd1b-4268-9b57-aee090ae3355
X-Runtime: 0.052177
Content-Length: 534

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "account_id": "PDz9n29e3m",
        "ticket_id": "AEgb5r9ejL",
        "contact_id": "VePJl7Y9ar",
        "sender": "person_29",
        "message": "Just wanted to follow up.",
        "media_url": null,
        "aborted": false,
        "sent": {
          "element_id": null,
          "element_type": null
        },
        "scheduled_for": 1781283659.194613,
        "created_at": 1781279459.1946082,
        "cancel_on": null,
        "aborter_id": null,
        "aborted_by": null,
        "abort_reason": null,
        "status_callback": null,
        "event_id": "3YnbgeJae2",
        "element_id": "2jRbk681Pv",
        "element_type": "PendingMessage",
        "sent_at": 1781280059.19642
      }
    ]
  },
  "page": 1
}

Search Scheduled Messages by scheduled date

Search for matching Messages scheduled to send between a time range

Endpoint

GET /v1/messages/scheduled

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
query Query to search Messages (default: iterate through all scheduled messages) string
page Page to request (default: 1) integer
from Phone number message will be sent from string
to Phone number message will be sent to string
contact_id Contact ID, filter messages scheduled to send to this Contact string
ticket_id Ticket ID, filter messages scheduled within this Ticket string
sender_id User ID who sent this message, filter messages scheduled by this User string
scheduled_for[from] Select messages scheduled to send after this date (default: now) unix_timestamp
scheduled_for[to] Select messages scheduled to send before this date (default: one year from now) unix_timestamp
created_at[from] Select scheduled messages created after this date unix_timestamp
created_at[to] Select scheduled messages created before this date (default: now) unix_timestamp

Request

Route

GET /v1/messages/scheduled?auth_id=YOobKd97E4&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=&page=1&scheduled_for%5Bfrom%5D=1781280059.646985&scheduled_for%5Bto%5D=1783872059.646998&document=false

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=YOobKd97E4
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=
page=1
scheduled_for={"from" => "1781280059.646985", "to" => "1783872059.646998"}
document=false

cURL

curl -g "https://www.avochato.com/v1/messages/scheduled?auth_id=YOobKd97E4&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=&page=1&scheduled_for%5Bfrom%5D=1781280059.646985&scheduled_for%5Bto%5D=1783872059.646998&document=false" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 95ac419e-71f3-41dc-a398-d1568d854d5e
X-Runtime: 0.034936
Content-Length: 533

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "account_id": "YOobKd97E4",
        "ticket_id": "xoWbqYbqnB",
        "contact_id": "enL8aAl87N",
        "sender": "person_31",
        "message": "Just wanted to follow up.",
        "media_url": null,
        "aborted": false,
        "sent": {
          "element_id": null,
          "element_type": null
        },
        "scheduled_for": 1781283659.603348,
        "created_at": 1781279459.603267,
        "cancel_on": null,
        "aborter_id": null,
        "aborted_by": null,
        "abort_reason": null,
        "status_callback": null,
        "event_id": "z1N8x2937L",
        "element_id": "PxB9NV9YOy",
        "element_type": "PendingMessage",
        "sent_at": 1781280059.60549
      }
    ]
  },
  "page": 1
}

Search Scheduled Uncancelled Messages

Search for any scheduled messages that have not been cancelled

Endpoint

GET /v1/messages/scheduled

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
query Query to search Messages (default: iterate through all scheduled messages) string
page Page to request (default: 1) integer
from Phone number message will be sent from string
to Phone number message will be sent to string
contact_id Contact ID, filter messages scheduled to send to this Contact string
ticket_id Ticket ID, filter messages scheduled within this Ticket string
sender_id User ID who sent this message, filter messages scheduled by this User string
scheduled_for[from] Select messages scheduled to send after this date (default: now) unix_timestamp
scheduled_for[to] Select messages scheduled to send before this date (default: one year from now) unix_timestamp
created_at[from] Select scheduled messages created after this date unix_timestamp
created_at[to] Select scheduled messages created before this date (default: now) unix_timestamp

Request

Route

GET /v1/messages/scheduled?auth_id=3o48Og8eAv&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=aborted%3A+false&page=1&document=false

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=3o48Og8eAv
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=aborted: false
page=1
document=false

cURL

curl -g "https://www.avochato.com/v1/messages/scheduled?auth_id=3o48Og8eAv&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=aborted%3A+false&page=1&document=false" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: e2dbb12e-6c69-49f2-8ab6-ed4f49643657
X-Runtime: 0.042476
Content-Length: 533

Body

{
  "status": 200,
  "data": {
    "messages": [
      {
        "account_id": "3o48Og8eAv",
        "ticket_id": "Pwebo1JXmD",
        "contact_id": "xDjJBnRJoO",
        "sender": "person_30",
        "message": "Just wanted to follow up.",
        "media_url": null,
        "aborted": false,
        "sent": {
          "element_id": null,
          "element_type": null
        },
        "scheduled_for": 1781283659.425357,
        "created_at": 1781279459.425353,
        "cancel_on": null,
        "aborter_id": null,
        "aborted_by": null,
        "abort_reason": null,
        "status_callback": null,
        "event_id": "3o48Og8eAv",
        "element_id": "enL8alJ7Nw",
        "element_type": "PendingMessage",
        "sent_at": 1781280059.42719
      }
    ]
  },
  "page": 1
}

Send Live Chat Message

Send a Live Chat Message to an active live chat session using the live chat session identifier.

Endpoint

POST /v1/messages

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Live chat contact identifier e.g. "avochato:c:XXXX-YYYY-ZZZZ" string
message required Text to send to the recipient string
mark_addressed Mark this conversation as "addressed" (default: false) boolean
media_url Media attachment to send via MMS (500kb limit) url
tags Comma-separated list of tags to apply to this contact string
status_callback Send a callback via http POST to this domain when the delivery status is updated url
send_as_user_id Send on behalf of another user (match by ID). That user must belong to this API token's account. string
send_as_user_email Send on behalf of another user (match by email). That user must belong to this API token's account. string

Request

Route

POST /v1/messages

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "v7Mb6NbERA",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "avochato:c:XXXX-YYYY-ZZZZ",
  "message": "test message",
  "mark_addressed": "true",
  "tags": "Some Tag, Another Tag",
  "status_callback": "https://my.domain.com",
  "send_as_user_email": "test-2@test.com"
}

cURL

curl "https://www.avochato.com/v1/messages" -d '{"auth_id":"v7Mb6NbERA","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"avochato:c:XXXX-YYYY-ZZZZ","message":"test message","mark_addressed":"true","tags":"Some Tag, Another Tag","status_callback":"https://my.domain.com","send_as_user_email":"test-2@test.com"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 82c00bfe-e68a-416f-8b8a-0aced7e2327f
X-Runtime: 0.166658
Content-Length: 804

Body

{
  "status": 200,
  "data": {
    "message": {
      "uuid": "c5ff4141-699a-48dc-a1c0-fff8a3924278",
      "account_id": "v7Mb6NbERA",
      "ticket_id": "v5D9R5bVAL",
      "contact_id": "0nMJLyk8vZ",
      "sender_id": "3OLb4Y94Ym",
      "sender_type": "User",
      "broadcast_id": null,
      "salesforce_activity_id": null,
      "salesforce_group_activity_id": null,
      "to": "avochato:c:XXXX-YYYY-ZZZZ",
      "from": "avochato:a:v7Mb6NbERA",
      "direction": "out",
      "origin": "api",
      "message": "test message",
      "contents": [],
      "segments": 1,
      "carrier": "avochato",
      "external_id": "AVOSM3ad39d24df88497bae37c6f45e4c3",
      "status": "queued",
      "error_code": 0,
      "error_description": null,
      "reason": null,
      "status_callback": "https://my.domain.com",
      "created_at": 1781280059.91879,
      "sent_at": 1781280059.91239,
      "content_blocked": null,
      "boost_multiplier": 1,
      "event_id": "Pe6bez9Xwy",
      "element_id": "k5V9Vz9lrR",
      "element_type": "SmsMessage"
    }
  }
}

Send Message

Send a Message to any Contact based on their phone

Endpoint

POST /v1/messages

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number to send the message to string
message required Text to send to the recipient string
from (E.164 format) Phone Number to use to send this message. Must be a valid Avochato number that belongs to this inbox. string
mark_addressed Mark this conversation as "addressed" (default: false) boolean
media_url Media attachment to send via MMS (500kb limit) url
tags Comma-separated list of tags to apply to this contact string
status_callback Send a callback via http POST to this domain when the delivery status is updated url
send_as_user_id Send on behalf of another user (match by ID). That user must belong to this API token's account. string
send_as_user_email Send on behalf of another user (match by email). That user must belong to this API token's account. string

Request

Route

POST /v1/messages

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "1K2b2vbWRy",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+14155553333",
  "message": "test message",
  "from": "+15105551234",
  "mark_addressed": "true",
  "tags": "Some Tag, Another Tag",
  "status_callback": "https://my.domain.com",
  "send_as_user_email": "test-2@test.com"
}

cURL

curl "https://www.avochato.com/v1/messages" -d '{"auth_id":"1K2b2vbWRy","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+14155553333","message":"test message","from":"+15105551234","mark_addressed":"true","tags":"Some Tag, Another Tag","status_callback":"https://my.domain.com","send_as_user_email":"test-2@test.com"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: c46548b6-76ff-4988-b820-04faf8a8f716
X-Runtime: 0.186158
Content-Length: 787

Body

{
  "status": 200,
  "data": {
    "message": {
      "uuid": "5677ffb7-b635-427f-b80d-58de08fbe9c4",
      "account_id": "1K2b2vbWRy",
      "ticket_id": "BLP9MzeJqY",
      "contact_id": "AwebYqobaE",
      "sender_id": "Pwebo1JXmD",
      "sender_type": "User",
      "broadcast_id": null,
      "salesforce_activity_id": null,
      "salesforce_group_activity_id": null,
      "to": "+14155553333",
      "from": "+15105551234",
      "direction": "out",
      "origin": "api",
      "message": "test message\n(Account 30: Reply STOP to opt out)",
      "contents": [],
      "segments": 1,
      "carrier": "anything",
      "external_id": null,
      "status": "queued",
      "error_code": 0,
      "error_description": null,
      "reason": null,
      "status_callback": "https://my.domain.com",
      "created_at": 1781280060.86626,
      "sent_at": 1781280060.86429,
      "content_blocked": null,
      "boost_multiplier": 1,
      "event_id": "wd6Jmzz87m",
      "element_id": "3o48Og8eAv",
      "element_type": "SmsMessage"
    }
  }
}

Send a Scheduled Message

Schedule a Message to deliver to a Contact at a specific date and time in the future

Endpoint

POST /v1/messages

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number to send the message to string
message required Text to send to the recipient string
scheduled_for required Unix Timestamp, Schedule this message to send at a date in the future unix_timestamp
from (E.164 format) Phone Number to use to send this message. Must be a valid Avochato number that belongs to this inbox. string
mark_addressed Mark this conversation as "addressed" (default: false) boolean
media_url Media attachment to send via MMS (500kb limit) url
tags Comma-separated list of tags to apply to this contact string
status_callback Send a callback via http POST to this domain when the delivery status is updated url
send_as_user_id Send on behalf of another user (match by ID). That user must belong to this API token's account. string
send_as_user_email Send on behalf of another user (match by email). That user must belong to this API token's account. string

Request

Route

POST /v1/messages

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "RkAJvlb0oL",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+14155553333",
  "message": "test message",
  "scheduled_for": 1781280658.4486551,
  "from": "+15105551234",
  "mark_addressed": "true",
  "tags": "Some Tag, Another Tag",
  "status_callback": "https://my.domain.com",
  "send_as_user_email": "test-2@test.com"
}

cURL

curl "https://www.avochato.com/v1/messages" -d '{"auth_id":"RkAJvlb0oL","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+14155553333","message":"test message","scheduled_for":1781280658.4486551,"from":"+15105551234","mark_addressed":"true","tags":"Some Tag, Another Tag","status_callback":"https://my.domain.com","send_as_user_email":"test-2@test.com"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: d67ffa7f-e8cf-45aa-af5b-7a65ef01b008
X-Runtime: 0.183565
Content-Length: 522

Body

{
  "status": 200,
  "data": {
    "message": {
      "account_id": "RkAJvlb0oL",
      "ticket_id": "1K2b2vbWRy",
      "contact_id": "wEG8j28QlW",
      "sender": "person_25",
      "message": "test message",
      "media_url": null,
      "aborted": false,
      "sent": {
        "element_id": null,
        "element_type": null
      },
      "scheduled_for": 1781280658.0,
      "created_at": 1781280058.605291,
      "cancel_on": null,
      "aborter_id": null,
      "aborted_by": null,
      "abort_reason": null,
      "status_callback": "https://my.domain.com",
      "event_id": "qQR9178geK",
      "element_id": "VePJlY8ar6",
      "element_type": "PendingMessage",
      "sent_at": 1781280058.60487
    }
  }
}

Tags

Add Tag (Contact id)

You can add a new tag to Contacts

Endpoint

POST /v1/contacts/:ids/tags

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of Contact ids to tag
tag required Tag to add to Contacts

Request

Route

POST /v1/contacts/GeAbZv3bDM%2CxoWbqpY8qn/tags

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "KRg80KaJj0",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "tag": "my-new-tag"
}

cURL

curl "https://www.avochato.com/v1/contacts/GeAbZv3bDM%2CxoWbqpY8qn/tags" -d '{"auth_id":"KRg80KaJj0","auth_secret":"YYYYYYYYYYYYYYYYYYYY","tag":"my-new-tag"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 5665ba26-83fa-4632-84b2-a384b369a9a6
X-Runtime: 0.038493
Content-Length: 94

Body

{
  "status": 200,
  "data": {
    "action": "tagged",
    "tag": "my-new-tag",
    "ids": [
      "GeAbZv3bDM",
      "xoWbqpY8qn"
    ]
  }
}

Add Tag (Phone)

You can add a new tag to a Contact based on phone number

Endpoint

POST /v1/tags

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number of the Contact
tag required Tag to add to Contacts

Request

Route

POST /v1/tags

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "qQR91D7bge",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+15551234567",
  "tag": "my-new-tag"
}

cURL

curl "https://www.avochato.com/v1/tags" -d '{"auth_id":"qQR91D7bge","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+15551234567","tag":"my-new-tag"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 30b2a93f-7fad-441a-aeae-ab8295e54f96
X-Runtime: 0.043015
Content-Length: 81

Body

{
  "status": 200,
  "data": {
    "action": "tagged",
    "tag": "my-new-tag",
    "ids": [
      "43y832xJVN"
    ]
  }
}

List All Tags

Returns a paginated list of Tags in this inbox

Endpoint

GET /v1/tags

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
page Page to request

Request

Route

GET /v1/tags?auth_id=M3NbrBKbr6&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=M3NbrBKbr6
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/tags?auth_id=M3NbrBKbr6&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: d49a57a5-04e6-42a2-9014-3bcf60103c57
X-Runtime: 0.049497
Content-Length: 111

Body

{
  "status": 200,
  "data": {
    "tags": [
      {
        "name": "my-old-tag"
      },
      {
        "name": "my-new-tag"
      }
    ],
    "last_key": "my-new-tag"
  },
  "limit": 30
}

Remove Tag (Contact id)

You can remove an old tag from Contacts

Endpoint

DELETE /v1/contacts/:ids/tags

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL) Comma separated list of Contact ids to untag
tag required Tag to remove from Contacts

Request

Route

DELETE /v1/contacts/xlYJplqJmw%2Cv5D9R058VA/tags

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "0N6bwZR8DM",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "tag": "my-old-tag"
}

cURL

curl "https://www.avochato.com/v1/contacts/xlYJplqJmw%2Cv5D9R058VA/tags" -d '{"auth_id":"0N6bwZR8DM","auth_secret":"YYYYYYYYYYYYYYYYYYYY","tag":"my-old-tag"}' -X DELETE \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: f49c6154-53ca-4f5f-9569-520c7e0ef6f3
X-Runtime: 0.080393
Content-Length: 96

Body

{
  "status": 200,
  "data": {
    "action": "untagged",
    "tag": "my-old-tag",
    "ids": [
      "xlYJplqJmw",
      "v5D9R058VA"
    ]
  }
}

Remove Tag (Phone)

You can remove an old tag from a Contact based on phone number

Endpoint

DELETE /v1/tags

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
phone required Phone number of the Contact
tag required Tag to remove from Contacts

Request

Route

DELETE /v1/tags

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "k5V9Vxz8lr",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+15551234567",
  "tag": "my-old-tag"
}

cURL

curl "https://www.avochato.com/v1/tags" -d '{"auth_id":"k5V9Vxz8lr","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+15551234567","tag":"my-old-tag"}' -X DELETE \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: f0a6e77b-2999-4b90-aca9-ecdb1131cfe3
X-Runtime: 0.028363
Content-Length: 83

Body

{
  "status": 200,
  "data": {
    "action": "untagged",
    "tag": "my-old-tag",
    "ids": [
      "VePJlYY8ar"
    ]
  }
}

Ticket Assignment

Ticket Assignment represents which user on your team owns a conversation. The owner assigned to a conversation will receive notifications of incoming calls and texts from that contact.

Auto Assign

You can automatically reassign one or more Tickets to any user in the Auto Assignment Roster by id. If there are no active users in your Auto Assignment Roster, ownership will remain unchanged. See Settings > Auto Assignment

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
user_id required autoassign string

Request

Route

PUT /v1/tickets/RkAJvlb0oL

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "qxk9EVJRKA",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "user_id": "autoassign"
}

cURL

curl "https://www.avochato.com/v1/tickets/RkAJvlb0oL" -d '{"auth_id":"qxk9EVJRKA","auth_secret":"YYYYYYYYYYYYYYYYYYYY","user_id":"autoassign"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 56b97a05-303d-47b0-9725-cd851705090e
X-Runtime: 0.220708
Content-Length: 490

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "RkAJvlb0oL",
        "uuid": "5f8bc7bb-2e90-4eaa-a46a-c50854cea1bf",
        "contact": "Pe6bez9Xwy",
        "user_id": "NEnJdQ8RmO",
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280056.950295,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Unassign

You can unassign one or more Tickets by id.

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
user_id required unassign string

Request

Route

PUT /v1/tickets/v7Mb6NbERA

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "AwebYoJaEr",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "user_id": "unassign"
}

cURL

curl "https://www.avochato.com/v1/tickets/v7Mb6NbERA" -d '{"auth_id":"AwebYoJaEr","auth_secret":"YYYYYYYYYYYYYYYYYYYY","user_id":"unassign"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: e7cbe730-afc0-4d2d-a7a8-36cb4a5c5d36
X-Runtime: 0.024475
Content-Length: 482

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "v7Mb6NbERA",
        "uuid": "aed5913e-1562-47da-bac6-ada1c59e79aa",
        "contact": "Pwebo1JXmD",
        "user_id": null,
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280058.049016,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Update Assignment with user_email

You can assign a User to be the owner of one or more Tickets by email.

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
user_email User email of the new owner string

Request

Route

PUT /v1/tickets/1LxJDK9n26%2CPDz9n29e3m

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "kvnJAeJADM",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "user_email": "person_19@example.com"
}

cURL

curl "https://www.avochato.com/v1/tickets/1LxJDK9n26%2CPDz9n29e3m" -d '{"auth_id":"kvnJAeJADM","auth_secret":"YYYYYYYYYYYYYYYYYYYY","user_email":"person_19@example.com"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 7e9a574a-13e7-433b-ae88-2ff32f178f2a
X-Runtime: 0.146782
Content-Length: 942

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "1LxJDK9n26",
        "uuid": "88ab6390-a824-4779-9ac5-ccf1ec399215",
        "contact": "EZA9P5Jrwg",
        "user_id": "RkAJvlb0oL",
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280057.398273,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      },
      {
        "id": "PDz9n29e3m",
        "uuid": "cf391ed4-30be-4405-bf0a-9130bfd250c4",
        "contact": "mQL9W79Wqz",
        "user_id": "RkAJvlb0oL",
        "unaddressed": false,
        "status": "Open",
        "origin": "Avochato",
        "created_at": 1781280057.439252,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Update Assignment with user_id

You can assign a User to be the owner of one or more Tickets by id.

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
user_id User ID of the new owner string

Request

Route

PUT /v1/tickets/3o48Og8eAv%2CYOobKd97E4

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "NEnJdQ8RmO",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "user_id": "1LxJDK9n26"
}

cURL

curl "https://www.avochato.com/v1/tickets/3o48Og8eAv%2CYOobKd97E4" -d '{"auth_id":"NEnJdQ8RmO","auth_secret":"YYYYYYYYYYYYYYYYYYYY","user_id":"1LxJDK9n26"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: c09dc657-8df2-401b-85e9-9538e91f10cb
X-Runtime: 0.119079
Content-Length: 942

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "3o48Og8eAv",
        "uuid": "6f83d867-b29d-460c-b0bd-30284dc98b6a",
        "contact": "AEgb5r9ejL",
        "user_id": "1LxJDK9n26",
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280057.7515619,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      },
      {
        "id": "YOobKd97E4",
        "uuid": "86662e75-35e9-427d-b9b1-d11a1481c2cb",
        "contact": "zPG9yg8aO0",
        "user_id": "1LxJDK9n26",
        "unaddressed": false,
        "status": "Open",
        "origin": "Avochato",
        "created_at": 1781280057.80768,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Ticket Status

Ticket Status represents the state of a conversation, and can be used to organize your inbox. Tickets marked as Closed are archived and do not appear in the inbox by default.

Close a Ticket

Mark one or more Tickets as Closed. Note: this will also automatically mark the ticket as ‘Addressed’

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
status Use the 'Closed' Status to close a ticket string

Request

Route

PUT /v1/tickets/wd6Jmz87m3

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "VePJlY8ar6",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "status": "Closed"
}

cURL

curl "https://www.avochato.com/v1/tickets/wd6Jmz87m3" -d '{"auth_id":"VePJlY8ar6","auth_secret":"YYYYYYYYYYYYYYYYYYYY","status":"Closed"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 270c36d3-0c61-43e1-8f3e-c2d084ce507a
X-Runtime: 0.329360
Content-Length: 481

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "wd6Jmz87m3",
        "uuid": "bfb74e0a-94ab-47ca-8962-24b1f0974ada",
        "contact": "wd6Jmz87m3",
        "user_id": null,
        "unaddressed": false,
        "status": "Closed",
        "origin": "Avochato",
        "created_at": 1781280052.696376,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Update Status

You can update the status of one or more Tickets

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
status The current Ticket Status. Options include "New", Open", "Pending", "Closed" string

Request

Route

PUT /v1/tickets/ezjJ7L85yZ%2CxDjJBRJoOe

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "ezjJ7L85yZ",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "status": "Pending"
}

cURL

curl "https://www.avochato.com/v1/tickets/ezjJ7L85yZ%2CxDjJBRJoOe" -d '{"auth_id":"ezjJ7L85yZ","auth_secret":"YYYYYYYYYYYYYYYYYYYY","status":"Pending"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 6672fcd4-4e8e-4b10-9454-b7fc5513546e
X-Runtime: 0.147418
Content-Length: 938

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "ezjJ7L85yZ",
        "uuid": "2186fce5-b0a4-4ef0-a6d4-53301ba5b84e",
        "contact": "ezjJ7L85yZ",
        "user_id": null,
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280053.428181,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      },
      {
        "id": "xDjJBRJoOe",
        "uuid": "b051eedf-b93a-4b70-ad42-9109bce01685",
        "contact": "xDjJBRJoOe",
        "user_id": "ezjJ7L85yZ",
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280053.5651689,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

Tickets

Tickets represent a unique conversation with a Contact in an Avochato Account.

Fetch Previous Tickets

You can fetch information about previous tickets by source ticket id

Endpoint

GET /v1/tickets/:id/previous

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
id required (URL parameter) Source Ticket id string

Request

Route

GET /v1/tickets/0N6bwR8DML/previous?auth_id=0N6bwR8DML&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=0N6bwR8DML
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/tickets/0N6bwR8DML/previous?auth_id=0N6bwR8DML&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: ad55efc2-b881-4e5c-aeba-3daa67526f70
X-Runtime: 0.031859
Content-Length: 326

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "qQR9178geK",
        "uuid": "88b6fd11-5949-4c8b-ab4c-6dce7e1cf99e",
        "channel": "sms",
        "contact": "v7Mb6NbERA",
        "created_at": 1781280056.29054,
        "closed_at": 1781276456.28919,
        "user": {
          "id": "M3NbrK9r6q",
          "name": "Person 14"
        },
        "device_type": null,
        "option_data": null,
        "tags": [],
        "account_subdomain": "account_13"
      }
    ]
  }
}

Fetch Tickets

You can fetch Tickets by ids

Endpoint

GET /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
page Page to request

Request

Route

GET /v1/tickets/0nMJLk9vZ2%2CBLP9Me9qYX?auth_id=qQR9178geK&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=qQR9178geK
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/tickets/0nMJLk9vZ2%2CBLP9Me9qYX?auth_id=qQR9178geK&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 1a00a37f-9997-4007-b665-0cc5e931bc0e
X-Runtime: 0.029168
Content-Length: 944

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "0nMJLk9vZ2",
        "uuid": "07ca96a9-8406-42e3-9226-451aff7b558d",
        "contact": "3o48Og8eAv",
        "user_id": "0N6bwR8DML",
        "unaddressed": false,
        "status": "Open",
        "origin": "Avochato",
        "created_at": 1781280056.0689542,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      },
      {
        "id": "BLP9Me9qYX",
        "uuid": "de6a7de9-7852-47a1-a266-ce46e1357d6a",
        "contact": "PDz9n29e3m",
        "user_id": null,
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280056.006848,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  },
  "page": 1
}

List all Tickets

You can retrieve a paginated list of all Tickets within an account

Endpoint

GET /v1/tickets

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
page Page to request

Request

Route

GET /v1/tickets?auth_id=M3NbrK9r6q&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=M3NbrK9r6q
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/tickets?auth_id=M3NbrK9r6q&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a3900f0a-0fcb-46ae-97d0-adc37dbd14af
X-Runtime: 0.041925
Content-Length: 971

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "qxk9EVJRKA",
        "uuid": "9ae3e9cf-46dc-4805-a905-debb17acc7f5",
        "contact": "BDr8Gk8PlQ",
        "user_id": "k5V9Vz9lrR",
        "unaddressed": false,
        "status": "Open",
        "origin": "Avochato",
        "created_at": 1781280056.5412061,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      },
      {
        "id": "M3NbrK9r6q",
        "uuid": "b1651236-e7ca-43d6-bc5e-267ebecbf0fc",
        "contact": "z1N8x2937L",
        "user_id": null,
        "unaddressed": false,
        "status": "Pending",
        "origin": "Avochato",
        "created_at": 1781280056.470581,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ],
    "total_count": 2
  },
  "page": 1,
  "limit": 30
}

Search Tickets

You can search for matching Tickets based on a query

Endpoint

GET /v1/tickets

Parameters

Name Description
auth_id required Auth Id field
auth_secret required Authentication Secret field
query String to search Tickets with (default: iterate through all tickets)
page Page to request

Request

Route

GET /v1/tickets?auth_id=k5V9Vz9lrR&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=status%3AOpen&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=k5V9Vz9lrR
auth_secret=YYYYYYYYYYYYYYYYYYYY
query=status:Open
page=1

cURL

curl -g "https://www.avochato.com/v1/tickets?auth_id=k5V9Vz9lrR&auth_secret=YYYYYYYYYYYYYYYYYYYY&query=status%3AOpen&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 7ec41897-592f-492b-bf9a-5bb0b6fbe504
X-Runtime: 0.041369
Content-Length: 524

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "AwebYoJaEr",
        "uuid": "7d2f0704-f545-46b3-b097-9179bd2af9fc",
        "contact": "1K2b2vbWRy",
        "user_id": "qxk9EVJRKA",
        "unaddressed": false,
        "status": "Open",
        "origin": "Avochato",
        "created_at": 1781280056.8049831,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ],
    "total_count": 1
  },
  "page": 1,
  "limit": 30
}

Update Unaddressed

You can mark a ticket as Addressed or Unaddressed automatically

Endpoint

PUT /v1/tickets/:ids

Parameters

Name Description type
auth_id required Auth Id field
auth_secret required Authentication Secret field
ids required (URL parameter) Comma separated list of Ticket id(s) string
unaddressed Flag whether the current ticket remains unaddressed. True or False boolean

Request

Route

PUT /v1/tickets/enL8alJ7Nw

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "KRg80abj0q",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "unaddressed": false
}

cURL

curl "https://www.avochato.com/v1/tickets/enL8alJ7Nw" -d '{"auth_id":"KRg80abj0q","auth_secret":"YYYYYYYYYYYYYYYYYYYY","unaddressed":false}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 011015ef-dd46-4000-8e34-1b791fd3927f
X-Runtime: 0.061107
Content-Length: 490

Body

{
  "status": 200,
  "data": {
    "tickets": [
      {
        "id": "enL8alJ7Nw",
        "uuid": "d688b996-5f28-4510-b04e-3a60cce64004",
        "contact": "1LxJDK9n26",
        "user_id": "qQR9178geK",
        "unaddressed": false,
        "status": "Closed",
        "origin": "Avochato",
        "created_at": 1781280055.7853498,
        "device_type": null,
        "device": null,
        "helper_bot": false,
        "helper_bot_source_account": null,
        "os": null,
        "os_version": null,
        "browser": null,
        "browser_version": null,
        "ip": null,
        "widget_referrer_url": null,
        "active_survey_id": null,
        "summary": null,
        "summary_updated_at": null
      }
    ]
  }
}

User Roles

User Roles are notification preference templates you can define per inbox. When adding a new user via the API, you can pass a user_role_id to apply that template — setting their default notification preferences (SMS alerts, call alerts, push notifications, etc.) at invite time.

List User Roles

Returns a paginated list of all custom User Role notification templates defined for this inbox. Use the returned id when adding a new user (POST /v1/users) to apply the template’s notification preferences to that user.

Endpoint

GET /v1/user_roles

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
page Page of user roles to request (default: 1)

Request

Route

GET /v1/user_roles?auth_id=wd6Jmz87m3&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=wd6Jmz87m3
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/user_roles?auth_id=wd6Jmz87m3&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: ba30331d-9027-4aa9-819a-4b5053e58989
X-Runtime: 0.071801
Content-Length: 119

Body

{
  "status": 200,
  "data": {
    "user_roles": [
      {
        "id": "wd6Jmz87m3",
        "name": "Agent"
      },
      {
        "id": "VePJlY8ar6",
        "name": "Support"
      }
    ]
  },
  "page": 1
}

Users

Users are team members who have access to your Avochato account. Each User can send messages, view Tickets, and be assigned conversations. Use these endpoints to manage user onboarding, offboarding, roles, and account access.

Add a User

Add a user to this account. If the email matches an existing Avochato user, they are added to the account and receive a notification. If the email is new, a user is created and an invite email is sent so they can set their password. Pass user_role_id to apply a notification preference template to a brand-new user.

Endpoint

POST /v1/users

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
email required Email address of the user to add. If the user does not yet exist in Avochato, a new user will be created and an invite email sent.
role Permission level for the user in this account. One of: member (default), manager, or owner. Members can view and respond to conversations. Managers can also manage team settings. Owners have full account control including billing.
name Display name for the user (only used when creating a new user)
phone Phone number in E.164 format (e.g., +14155551234). If provided, triggers MFA phone setup so the user can complete two-factor authentication during onboarding.
user_role_id Encoded ID of a User Role notification template to apply to the new user. Use GET /v1/user_roles to list available templates and their IDs. Only applies when creating a brand-new Avochato user — existing users already have their own notification settings.

Request

Route

POST /v1/users

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "kvnJA1eJAD",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "email": "newuser@sunrisedental.com",
  "role": "member",
  "name": "Sarah Johnson"
}

cURL

curl "https://www.avochato.com/v1/users" -d '{"auth_id":"kvnJA1eJAD","auth_secret":"YYYYYYYYYYYYYYYYYYYY","email":"newuser@sunrisedental.com","role":"member","name":"Sarah Johnson"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 41e0db53-3b75-43df-ba6b-e001e8d4dfca
X-Runtime: 0.031246
Content-Length: 428

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": "newuser@sunrisedental.com",
      "id": "Pe6beazbXw",
      "name": "Sarah Johnson",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280076.743,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280076.74661
    }
  }
}

Add a User with a User Role

When adding a brand-new user, pass user_role_id (from GET /v1/user_roles) to apply a notification preference template. This sets the user’s default notification settings (SMS alerts, call alerts, push notifications, etc.) at invite time.

Endpoint

POST /v1/users

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
email required Email address of the user to add. If the user does not yet exist in Avochato, a new user will be created and an invite email sent.
role Permission level for the user in this account. One of: member (default), manager, or owner. Members can view and respond to conversations. Managers can also manage team settings. Owners have full account control including billing.
name Display name for the user (only used when creating a new user)
phone Phone number in E.164 format (e.g., +14155551234). If provided, triggers MFA phone setup so the user can complete two-factor authentication during onboarding.
user_role_id Encoded ID of a User Role notification template to apply to the new user. Use GET /v1/user_roles to list available templates and their IDs. Only applies when creating a brand-new Avochato user — existing users already have their own notification settings.

Request

Route

POST /v1/users

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "qxk9ELVbRK",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "email": "agent@sunrisedental.com",
  "role": "member",
  "name": "James Agent",
  "user_role_id": "ezjJ7L85yZ"
}

cURL

curl "https://www.avochato.com/v1/users" -d '{"auth_id":"qxk9ELVbRK","auth_secret":"YYYYYYYYYYYYYYYYYYYY","email":"agent@sunrisedental.com","role":"member","name":"James Agent","user_role_id":"ezjJ7L85yZ"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 07859d40-d8b7-4996-8604-f69b8358f0e3
X-Runtime: 0.160679
Content-Length: 428

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": "agent@sunrisedental.com",
      "id": "z1N8xD2837",
      "name": "James Agent",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280076.5288799,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280076.53503
    }
  }
}

Delete a User

Permanently remove a user from this account. Unlike disabling, this completely removes the user’s membership — their tickets will be unassigned and they will lose all access. The user’s Avochato account still exists and they can be re-added later.

Endpoint

DELETE /v1/users/:id

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User to delete. You can use the user's email instead.
email Email address of the user to delete. Alternative to passing the encoded ID in the URL.

Request

Route

DELETE /v1/users/PxB9NXV8YO

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "3o48OvgJeA",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/users/PxB9NXV8YO" -d '{"auth_id":"3o48OvgJeA","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X DELETE \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a5722e78-766c-4bf3-a504-5a3d43b63be9
X-Runtime: 0.030633
Content-Length: 72

Body

{
  "status": 200,
  "data": {
    "message": " has been removed from this account."
  }
}

Disable a User

Disable a user in this account. The user will lose access to the account and will no longer receive notifications or be assigned conversations. Their conversation history is preserved.

Endpoint

POST /v1/users/:id/disable

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User to disable. You can use the user's email instead.
email Email address of the user to disable. Alternative to passing the encoded ID in the URL.

Request

Route

POST /v1/users/xoWbqpY8qn/disable

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "RkAJvDlb0o",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/users/xoWbqpY8qn/disable" -d '{"auth_id":"RkAJvDlb0o","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a1a00cad-acc6-44b1-9e19-7b2cb49f7eaf
X-Runtime: 0.040709
Content-Length: 404

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": null,
      "id": "xoWbqpY8qn",
      "name": "Bob McTest",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280077.0037,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": false,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280077.00605
    }
  }
}

Get User Details

Retrieve detailed information about a specific User, including their role, enabled status, permissions (can_message, can_call, can_view_billing, can_view_org), MFA status, last login date, and the date they were added to the account.

Endpoint

GET /v1/users/:id

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User to retrieve. You can use the user's email instead — pass it as the email parameter.
email Email address of the user to look up. Alternative to passing the encoded ID in the URL.

Request

Route

GET /v1/users/wd6Jmxp97m?auth_id=v7Mb6WN9ER&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=v7Mb6WN9ER
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/users/wd6Jmxp97m?auth_id=v7Mb6WN9ER&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: ef7705af-78fe-4ad0-b70d-68c0c73c9a3e
X-Runtime: 0.028634
Content-Length: 404

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": null,
      "id": "wd6Jmxp97m",
      "name": "Bob McTest",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280077.61412,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280077.61659
    }
  }
}

List User Inboxes

Returns a list of all inboxes (accounts) the specified user has access to within your organization. Each account includes its subdomain, name, phone number, and creation date. Results are scoped to your organization — you will not see accounts in other organizations.

Endpoint

GET /v1/users/:id/accounts

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User. You can use the user's email instead.
email Email address of the user. Alternative to passing the encoded ID in the URL.

Request

Route

GET /v1/users/EZA9Pl59rw/accounts?auth_id=NEnJdnQbRm&auth_secret=YYYYYYYYYYYYYYYYYYYY

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=NEnJdnQbRm
auth_secret=YYYYYYYYYYYYYYYYYYYY

cURL

curl -g "https://www.avochato.com/v1/users/EZA9Pl59rw/accounts?auth_id=NEnJdnQbRm&auth_secret=YYYYYYYYYYYYYYYYYYYY" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 96aa4fbc-06c8-4b0a-963f-25ec685afaa7
X-Runtime: 0.029905
Content-Length: 145

Body

{
  "status": 200,
  "data": {
    "accounts": [
      {
        "id": "3Ynbgne8ae",
        "subdomain": "account_61",
        "name": "Account 61",
        "phone": null,
        "created_at": 1781280076.788762
      }
    ]
  }
}

List all Users

Returns a paginated list of all Users within an account. Response includes each user’s email, name, phone number, last login date, MFA status, and creation date.

Endpoint

GET /v1/users

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
page Page of users to request (default: 1)

Request

Route

GET /v1/users?auth_id=3Ynbgne8ae&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1

Headers

Content-Type: application/json
Host: www.avochato.com

Query Parameters

auth_id=3Ynbgne8ae
auth_secret=YYYYYYYYYYYYYYYYYYYY
page=1

cURL

curl -g "https://www.avochato.com/v1/users?auth_id=3Ynbgne8ae&auth_secret=YYYYYYYYYYYYYYYYYYYY&page=1" -X GET \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: b4208dc7-69e2-41a9-9328-97267f3ac762
X-Runtime: 0.025388
Content-Length: 764

Body

{
  "status": 200,
  "data": {
    "users": [
      {
        "email": "person_69@example.com",
        "id": "wEG8jA2JQl",
        "name": "Person 48",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280077.09212,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      },
      {
        "email": null,
        "id": "xlYJplqJmw",
        "name": "Bob McTest",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280077.10495,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      },
      {
        "email": null,
        "id": "v5D9R058VA",
        "name": "Alice Rivera",
        "image_url": null,
        "signed_in_at": null,
        "avobot_id": null,
        "phone": null,
        "phone_formatted": null,
        "created_at": 1781280077.11004,
        "require_2fa": true,
        "mfa_app_valid": false,
        "phone_valid": false
      }
    ]
  },
  "page": 1
}

Re-enable a User

Re-enable a previously disabled user in this account. The user will regain access to the account. Requires manager or owner role.

Endpoint

POST /v1/users/:id/enable

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User to re-enable. You can use the user's email instead.
email Email address of the user to re-enable. Alternative to passing the encoded ID in the URL.

Request

Route

POST /v1/users/wd6Jmxz97m/enable

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "1LxJDvKbn2",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/users/wd6Jmxz97m/enable" -d '{"auth_id":"1LxJDvKbn2","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: a6f64205-a3ac-44b5-b461-49afa0fbe404
X-Runtime: 0.025112
Content-Length: 404

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": null,
      "id": "wd6Jmxz97m",
      "name": "Bob McTest",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280077.19903,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280077.20078
    }
  }
}

Set MFA Phone Number

Set or update the MFA phone number for a user. The phone number is set as pending until the user verifies it via SMS code. Requires org-level permissions.

Endpoint

POST /v1/users/:id/mfa_phone

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
phone required Phone number in E.164 format (e.g., +14155551234). This sets a pending MFA phone number — the user must verify it by entering the SMS code they receive.
id (URL) The encoded ID of the User. You can use the user's email instead.
email Email address of the user. Alternative to passing the encoded ID in the URL.

Request

Route

POST /v1/users/xDjJBNRJoO/mfa_phone

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "PDz9nV29e3",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "phone": "+14155559876",
  "private": true
}

cURL

curl "https://www.avochato.com/v1/users/xDjJBNRJoO/mfa_phone" -d '{"auth_id":"PDz9nV29e3","auth_secret":"YYYYYYYYYYYYYYYYYYYY","phone":"+14155559876","private":true}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 6823dca0-ad92-4f29-a86e-cb3a2e723e70
X-Runtime: 0.046175
Content-Length: 478

Body

{
  "status": 200,
  "data": {
    "message": "MFA phone number has been set. User must verify via SMS code.",
    "user": {
      "email": null,
      "id": "xDjJBNRJoO",
      "name": "Bob McTest",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280077.29356,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "member",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280077.29569
    }
  }
}

Trigger a Password Reset

Send a password reset email to the specified user. The user will receive an email with a link to set a new password. The link expires after 48 hours. Requires manager or owner role.

Endpoint

POST /v1/users/:id/password_reset

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
id (URL) The encoded ID of the User. You can use the user's email instead.
email Email address of the user to send a password reset to. Alternative to passing the encoded ID in the URL.

Request

Route

POST /v1/users/zPG9y3g8aO/password_reset

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "AwebYqobaE",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY"
}

cURL

curl "https://www.avochato.com/v1/users/zPG9y3g8aO/password_reset" -d '{"auth_id":"AwebYqobaE","auth_secret":"YYYYYYYYYYYYYYYYYYYY"}' -X POST \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: 37e6fa40-c099-4f97-a12e-acc0b1f883c1
X-Runtime: 0.028162
Content-Length: 65

Body

{
  "status": 200,
  "data": {
    "message": "Password reset email sent to "
  }
}

Update a User role

Change a user’s permission level in this account. Requires manager or owner role. Managers cannot promote users to owner or modify existing owners — only owners and admins can do that.

Endpoint

PUT /v1/users/:id

Parameters

Name Description
auth_id required Your API authentication ID. Find this in Settings > API Access.
auth_secret required Your API authentication secret. Pair this with auth_id for every request.
role required New role for the user. One of: member, manager, or owner.
id (URL) The encoded ID of the User to update. You can use the user's email instead.
email Email address of the user to update. Alternative to passing the encoded ID in the URL.

Request

Route

PUT /v1/users/0nMJLNkbvZ

Headers

Content-Type: application/json
Host: www.avochato.com

Body

{
  "auth_id": "YOobKadJ7E",
  "auth_secret": "YYYYYYYYYYYYYYYYYYYY",
  "role": "manager"
}

cURL

curl "https://www.avochato.com/v1/users/0nMJLNkbvZ" -d '{"auth_id":"YOobKadJ7E","auth_secret":"YYYYYYYYYYYYYYYYYYYY","role":"manager"}' -X PUT \
	-H "Version: HTTP/1.0" \
	-H "Content-Type: application/json" \
	-H "Host: www.avochato.com"

Response

Simulated Response

Status

200

Headers

Content-Type: application/json; charset=utf-8
X-Request-Id: cd011642-734a-452e-8c4d-ae2cfdfbb9d9
X-Runtime: 0.026198
Content-Length: 405

Body

{
  "status": 200,
  "data": {
    "user": {
      "email": null,
      "id": "0nMJLNkbvZ",
      "name": "Bob McTest",
      "image_url": null,
      "signed_in_at": null,
      "avobot_id": null,
      "phone": null,
      "phone_formatted": null,
      "created_at": 1781280077.52364,
      "require_2fa": true,
      "mfa_app_valid": false,
      "phone_valid": false,
      "role": "manager",
      "enabled": true,
      "can_message": true,
      "can_call": true,
      "can_view_billing": false,
      "can_view_org": false,
      "added_at": 1781280077.52763
    }
  }
}