Contact Us
Log inStart Free Trial

API reference / Get started

OpenAPI and Postman

The Drop Cowboy® API is described by an OpenAPI 3.1 spec. A Postman collection is generated from that spec, so the two always list the same routes. Use the spec to generate a client or to load the API into any tool that reads OpenAPI. Use the collection to try a route by clicking, before you write any code.

Downloads

File Address Use it to
OpenAPI spec /openapi.yaml Generate a client, validate requests, or browse the API in a documentation viewer
Postman collection DropCowboy-v2-Public-API.postman_collection.json Send any route from Postman
Postman environment DropCowboy-v2-Production.postman_environment.json Hold your base URL and API key pair for the collection

You don't need credentials to download any of them. The spec is also at https://api-v2.dropcowboy.com/openapi.yaml.

Use the OpenAPI spec

Any tool that reads OpenAPI 3.1 can load the spec: code generators, API clients and documentation viewers. Point the tool at https://www.dropcowboy.com/openapi.yaml, or download the file and open it.

Each route in the spec lists the scopes it needs. See Authentication for how scopes and keys work.

Import the Postman collection

  1. In Postman, choose Import and add both JSON files. You can drop in the downloaded files, or paste the address of each one.
  2. Pick the DropCowboy v2 Production environment in the environment menu at the top right.
  3. Open the environment and fill in api_key and api_secret with a key pair from Developers > API keys. Postman stores both as secret values. Save the environment.
  4. Open the Account folder and send Get your account. A 200 means the key works.

The collection has one folder per area of the API. Many requests need an id from your account. Use the list requests to find them, such as List phone lines in Phone numbers, List media files in Media and List lists in Lists.

How the collection signs requests

The collection adds the x-key and x-secret headers to every request from the api_key and api_secret variables, so you don't set them on each request. The collection doesn't set up OAuth. Use an API key pair.

The Building Blocks routes under /phone/embed/ take a site token instead of a key pair. Create one as described in Authentication and send it as Authorization: Bearer <token>.

Replace the example values

Request bodies and example responses come from the spec. Every id, phone number, email address and URL in them is made up. Replace them with your own values before you send.

The collection calls the live API. A send request sends a real message once you fill in real values, so send to your own test numbers first. The Quickstart shows how to set those up.

What the collection leaves out

  • Detection. Postman imports each OpenAPI operation as an HTTP request, and Detection runs over a WebSocket. Open a Postman WebSocket request to wss://detect.dropcowboy.com/carrier/ws, add an Authorization: Bearer header with your Detection key, and send the welcome message shown in Detection.
  • Webhooks. These are requests Drop Cowboy sends to your server. Their payloads are in Webhooks and in the webhooks section of the spec.

Keep your copy current

The spec and the collection change together. When the Changelog lists a new or changed route, download the files again and re-import the collection.