API documentation

AgencyAccess API

Create clients and access requests from your own software, embed them in your client portal, and follow every grant with signed webhooks. The API is available on the Premium and Agency plans and during your trial.

What you can build

Agencies and platforms use the API to put client onboarding where their clients already are: a CRM, a client portal or an onboarding flow. A typical integration:

  1. Creates the client (or finds it by your own ID) when a deal closes.
  2. Creates an access request for the services you need, such as Google Ads admin access.
  3. Sends the client the link, or shows it inside your portal.
  4. Receives a webhook as each service is granted, and when the request is complete.
Portal integrationThe end-to-end flow, from client to completed request. WebhooksSigned events as clients grant access, with retries. EmbeddingShow requests inside your portal and listen to their progress.

Quickstart

1. Create an API key. In the dashboard, go to API and create a key with the scopes your integration needs. The key is shown once; keep it on your server, for example in AGENCYACCESS_API_KEY.

2. Check it works.

Check your key 
curl "https://api.agencyaccess.co/api/v2/me" -H "Authorization: Bearer $AGENCYACCESS_API_KEY"

3. Create a client. The response's data.id is the client ID.

Create a client 
curl -X POST "https://api.agencyaccess.co/api/v2/clients" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{ "name": "Jamie Rivera", "email": "jamie@northwindcoffee.com", "externalClientId": "crm-4821" }
JSON

4. Create an access request. Find the services you can request with GET /services and your connected accounts with GET /accounts. The response includes the inviteUrl to send your client.

Create a request 
curl -X POST "https://api.agencyaccess.co/api/v2/requests" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "clientId": "CLIENT_ID",
  "requestedServices": {
    "Google Ads": { "accessLevel": "ADMIN", "requestedAccountLinks": [{ "internalAccountId": "ACCOUNT_ID" }] }
  }
}
JSON

5. Follow progress. Add a webhook for request.completed and service.granted, or read the request with GET /requests/{id}.

Basics

  • Base URL: https://api.agencyaccess.co/api/v2. Every call uses https.
  • Send your key as Authorization: Bearer aa_live_.... See Authentication.
  • Bodies and responses are JSON. Successful responses wrap the result in data; errors return error with a stable code. See Requests and errors.
  • Creates take an Idempotency-Key header, so retrying after a timeout with the same key and body doesn't create a duplicate or use more of your allowance.
  • Your agency can make 300 calls a minute.

Reference

ClientsThe businesses you request access from.RequestsAccess requests: the link a client opens to grant your agency access to their accounts, and the progress of each requested service..Accounts and servicesWhat a request can ask for: your agency's connected accounts that access is granted to, and the services and roles that can be requested..WebhooksEndpoints on your server that receive signed events as requests change.UsageYour plan and how much of this month's access link allowance you have used..AccountThe API key in use and its agency, to check a setup.. EventsEvery webhook event type and what it contains. OpenAPI specThe whole API as an OpenAPI 3.1 document for tools and code generators.