Create an API token and make your first request

The Swimlane public API lets your own scripts, n8n or Make read and write your contacts, lists, tags and pipelines. This guide creates a token and runs a first request in under five minutes.

Before you start

• You need access to Swimlane (an active subscription on your organization) to create a token.
• Open the organization you want the API to work on at least once in the app. A token always acts on the organization you last used (see Switch between organizations).

Create a token

1. Click Settings at the bottom of the left sidebar.
2. In the Integrations group, open API.
3. In the API Tokens card, click Add Token.
4. Give it a Token Name that says where it will be used, for example "n8n – HubSpot sync".
5. Click Create Token.
6. Copy the Generated Token with the copy button. It starts with wpa_.
7. Click Done.

The full token is shown only once. Store it in a password manager or as a credential in your automation tool. If you lose it, delete it and create a new one.

Make your first request

The API lives at https://api.getswimlane.com, and every endpoint starts with /v1. Send your token in the Authorization header:

curl "https://api.getswimlane.com/v1/contacts?per_page=2" \
  -H "Authorization: Bearer wpa_your_token_here"

You get the most recent contacts of your organization, newest first:

{
  "meta": {
    "total": 1284,
    "perPage": 2,
    "currentPage": 1,
    "lastPage": 642,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=642",
    "nextPageUrl": "/?page=2",
    "previousPageUrl": null
  },
  "data": [
    {
      "uuid": "3f0c5b1e-8d2a-4c1e-9f5b-2a7d6e1c9b40",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": null,
      "headline": "Head of Sales at Acme",
      "location": "Lyon, France",
      "linkedinId": "jane-doe-42",
      "archived": false,
      "listUuids": ["b8e2…"],
      "companyUuids": ["41aa…"],
      "tagIds": [12],
      "pipelineStageUuid": null,
      "createdAt": "2026-09-01T08:15:22.000+00:00",
      "updatedAt": "2026-09-12T16:40:03.000+00:00"
    }
  ]
}

Contacts carry a few more fields than shown here. The full list is in Swimlane public API reference.

Then try a write, for example creating a list:

curl -X POST "https://api.getswimlane.com/v1/lists" \
  -H "Authorization: Bearer wpa_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Webinar attendees"}'

Explore every endpoint

The interactive documentation is at https://api.getswimlane.com/docs. Click Authorize, paste your token, and you can run requests from the page.

Follow your API usage

Back in Settings → API, the API Usage card lists your recent calls with the method, path, status code, duration and date. It is the quickest way to see why an automation fails.

Good to know

• Rate limit: 100 requests per minute per Swimlane user. All your tokens share this budget. Each response tells you where you stand with the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers (the reset is a Unix timestamp in seconds). Past the limit you get 429 with rate_limit.exceeded.
• Pagination: page and per_page on list endpoints. per_page defaults to 50 and is capped at 100.
• Tokens last four years, then expire. To revoke one earlier, click the bin icon next to it in API Tokens. It is deleted at once, without a confirmation step.
• Only tokens from Settings → API work. They are tied to you: everyone in your team who needs the API creates their own.
• Changes made through the API don't trigger webhooks. Webhook events come from actions in the app and from Swimlane's own imports.

Troubleshooting

• 401 "Invalid or missing API token": the header is missing, the token was deleted or expired, or it is not a wpa_ token.
• 403 organization.required: your account has no organization selected. Log in to the app and open your organization, then retry.
• 404 resource.not_found: the uuid doesn't exist in the organization the token acts on. Check that you last used the right organization in the app.
• 422 validation.failed: the body is invalid. The errors array names the field.