Skip to main content

API reference

The Nickel API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Start building

Quickstart

Make your first API call and create an invoice in about five minutes.

Send an invoice and get paid

Create an invoice, email it, and track the payment end to end.

Pay a vendor bill

Pay vendor bills by ACH, check, or international wire through the API.

Receive webhooks

Get notified when something happens in your Nickel account.

Authorization and testing

The Nickel API uses Bearer Authentication. Organizations on the Nickel Pro plan create and manage API tokens in the dashboard under Settings → API. Each token is shown once at creation — store it securely. If you don’t have a Pro plan yet, get in touch about API access.
The interactive API playground on this site uses the staging environment. Make sure to use your sandbox API key when testing requests in the playground.
A token acts as the team member who created it. When you create one, you can also give it one of your organization’s roles: the token can then do only what that role allows, and never more than you can. Give each integration a role that holds only what it needs, so a key that creates bills and vendors can’t pay them. Changing the role, or your own role, changes what the token can do from its next request. Include your API key in the Authorization header of every request:

Requests and responses

For POST requests, set the Content-Type header to application/json and pass parameters in the JSON request body. For GET requests, pass parameters as query string parameters in the URL. All API responses return application/json.

Errors

The Nickel API uses standard HTTP response codes to indicate the success or failure of a request.
  • 2xx — Success
  • 4xx — Client error (invalid request, authentication failure, etc.)
  • 5xx — Server error
When an error occurs, the API returns a JSON object with an error field containing a human-readable description of the problem:
A 429 means your API key is sending requests faster than Nickel serves them, for one of two reasons. Both come with a Retry-After header, in seconds: wait that long, then retry.
  • Too many requests in flight at once. Nickel runs a few of each key’s requests at a time and holds the rest until one finishes, so a burst is slowed down rather than refused. A request still waiting after 15 seconds is answered 429. To fetch many records, keep no more than 10 requests in flight per key.
  • Too many requests in an hour. Each key can make 3,000 requests an hour, counted across everything it is used for, including the Nickel MCP server. Most requests count once; a few that do more work, such as updating an invoice, count two or three times. Past that, every request is answered 429 until the hour is up. A key reaches this by checking the same records over and over: to keep your own system up to date with payments, check each open invoice every few minutes rather than every few seconds, and stop checking once it’s paid.
A 403 means the API key isn’t allowed to make that request: the permissions it acts with don’t include one the request needs. The error message is Nickel’s own, and on the Nickel Banking endpoints it names the missing permission. Don’t retry a 403 as you would a 5xx: Nickel refuses the same request until the permission is granted, or you use a key that has it.