Building an Attio API integration requires querying object endpoints, paginating through record results, and handling HTTP 429 responses to stay within rate limits. For engineers at B2B SaaS companies, this means authenticating requests with OAuth 2.0, reading records in pages, and keeping a CRM data sync accurate over time. This guide walks through each step using Attio’s REST API.
Key Takeaways
- Authenticate your application using the OAuth 2.0 authorization code flow.
- Query
https://api.attio.com/v2/objects/{object}/records/queryto fetch records, replacing{object}with an object slug such aspeople. - Paginate with
limitandoffset, and stop when a page returns fewer results than the limit. - Handle HTTP 429 responses by parsing the
Retry-Afterheader as an HTTP date. - Use webhooks for supported list entry events instead of polling.
Attio CRM data model and sync patterns
Attio is a CRM built on a configurable data model. B2B SaaS applications pull this data to mirror customer details in their own databases. To build the sync, you query Attio’s API endpoints, follow its pagination rules, and map its data structures.
Syncing with several CRMs adds engineering overhead. What is API Integration? The 2026 Complete Guide covers the standard connection patterns and how different vendors operate. Because every CRM structures its data differently, maintaining direct connections forces your team to update separate pipelines whenever external schemas change.
With Knit: According to Knit’s unified CRM API documentation, CRM platforms each have their own APIs with different authentication methods and object models. Knit normalizes these differences so your engineering team integrates once. With an Attio API Integration through Knit, Knit runs the translation layer for every CRM your customers use.
Authenticating with the Attio API via OAuth 2.0
Attio secures its endpoints using standard web protocols. Attio’s authentication tutorials state that if you are building an app that needs to make requests to Attio’s REST API on behalf of many users, you should use OAuth 2.0 to authenticate your app. This authorization code flow grants an access token after the user approves the requested scopes.
Attio OAuth requires configuring a client application to obtain a Client ID and Client Secret. Your application directs users to the authorization URL, captures the callback code, and exchanges it for a token. You include this token in the Authorization: Bearer header on every subsequent request to the API.
With Knit: Knit’s Attio guide explains that Knit’s own OAuth app is used in the authorization flow by default. To use your own Attio app instead, create it at build.attio.com, add
https://app.getknit.dev/oauth/authorizeas a redirect URI, and give Knit your Client ID and Client Secret, for example through the Client OAuth Credentials API:POST https://api.getknit.dev/v1.0/integration.registerOauthCreds Authorization: Bearer <YOUR_KNIT_API_KEY> Content-Type: application/json { "appId": "attio", "clientId": "your_client_id", "clientSecret": "your_client_secret" }
Querying Objects and Records in Attio
The Attio API base URL is https://api.attio.com/v2, as shown in Attio’s server SDK documentation. All requests exchange JSON payloads over HTTPS and require standard content-type headers.
To retrieve records, Attio’s records endpoint reference uses the POST method. The URL path is https://api.attio.com/v2/objects/{object}/records/query. Replace {object} with an object slug such as people, or with the object’s UUID.
The example below lists records from one object:
POST https://api.attio.com/v2/objects/{object}/records/query
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json
{
"limit": 100,
"offset": 0
}
Handling Attio API Pagination
Bulk data comes back in pages. Attio’s pagination guide describes limit/offset pagination with two parameters: limit, the number of results per request, and offset, the number of results to skip, which defaults to 0.
Each endpoint sets its own default and maximum. The records query reference gives a default limit of 500 and does not state a maximum, so check the page for the endpoint you call. The List record entries reference gives a default of 100 and a maximum of 1000 for that endpoint.
To paginate, increment offset by limit after each page. The stop condition is: stop when a page returns fewer results than the limit. This avoids the extra request that an empty-page check would need.
The loop below pages through every record in one object, reading the data array from each response, and waits out any HTTP 429 response:
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
import requests
BASE_URL = "https://api.attio.com/v2"
HEADERS = {"Authorization": "Bearer <YOUR_ACCESS_TOKEN>"}
def fetch_all_records(object_slug, limit=500):
"""Page through an object's records until a short page signals the end."""
url = f"{BASE_URL}/objects/{object_slug}/records/query"
records, offset = [], 0
while True:
resp = requests.post(
url, headers=HEADERS, json={"limit": limit, "offset": offset}, timeout=30
)
if resp.status_code == 429:
# Retry-After is an HTTP date, not a number of seconds.
reset_at = parsedate_to_datetime(resp.headers["Retry-After"])
wait = (reset_at - datetime.now(timezone.utc)).total_seconds()
time.sleep(max(1.0, wait))
continue
resp.raise_for_status()
page = resp.json()["data"]
records.extend(page)
if len(page) < limit:
return records
offset += limit
people = fetch_all_records("people")
Syncing Real-Time Events with Attio Webhooks
Polling list endpoints is one way to detect changes. Attio also documents webhooks, which push events to your server so you can avoid polling for supported events.
Each subscription takes an event type and an optional filter. The guide’s examples use list entry events: list-entry.created, list-entry.updated, and list-entry.deleted. It notes that these replace the deprecated V1 events entry.created, entry-attribute.updated, and entry.deleted, and fire under exactly the same circumstances. A subscription can be limited to one list with a filter on id.list_id. Each combination of target URL, event type, and filter must be unique in a workspace, and a duplicate returns HTTP 409. You can create webhooks through the API or the developer settings page. Webhooks created with OAuth-issued tokens do not appear on the settings page.
Managing Attio API Rate Limits
High-volume data syncs often hit vendor rate limits. When your application exceeds the allowed request volume, Attio returns an HTTP 429 status code, as described in Attio’s rate limiting guide. The guide sets the limits at 100 requests per second for reads and 25 requests per second for writes, across the whole API. Your client must catch this error and pause requests.
Attio includes a Retry-After header in the HTTP 429 response. This header is formatted as an HTTP date, not a number of seconds. For example, it appears as Tue, 23 May 2023 14:42:01 GMT. Parse it as a date, compare it to the current system time, and pause execution until that time passes.
Frequently Asked Questions
How do I authenticate my integration with the Attio API using OAuth 2.0?
You authenticate by using the OAuth 2.0 authorization code flow. According to Attio’s documentation, you must use this flow if you are building an application that needs to make requests to the API on behalf of many users. It requires a Client ID and Client Secret to generate an access token.
How do I write a query to fetch objects and records from Attio?
You fetch records by making a POST request to https://api.attio.com/v2/objects/{object}/records/query. You replace {object} in the URL with an object slug, and you include the authorization token in the headers alongside a JSON body containing your limit and offset parameters.
How does Attio API pagination work and when does the pagination loop stop?
Attio API pagination works using limit and offset parameters in the JSON request body. You increment the offset by the limit on each subsequent request. You stop the pagination loop when a page returns fewer results than the limit.
How do I handle Attio API rate limits (HTTP 429) and properly read the Retry-After header?
You handle rate limits by intercepting HTTP 429 status codes. The response includes a Retry-After header formatted as an HTTP date (for example, Tue, 23 May 2023 14:42:01 GMT). Parse this header as a date rather than an integer of seconds, and pause your requests until that time passes.
Does Attio support webhooks for real-time CRM sync?
Yes. Attio’s REST API guide documents webhooks for list entry events, including list-entry.created, list-entry.updated, and list-entry.deleted. You can create subscriptions through the API or the developer settings page.