Overview

This page documents the Rankley API endpoints used by the Rankley Zapier integration.

Rankley’s Zapier integration currently supports:

API key authentication
New Account Created trigger
New Report Completed trigger
Account selection fields used inside Zapier

This documentation is intended for Zapier reviewers, technical users, and integration partners.

Looking for the customer setup guide?
See Connect Rankley to Zapier for step-by-step instructions on generating an API key and building a Zap.

Base URL

Production base URL:

https://app.rankley.com

All API endpoints are under:

/api/v1/

Example full API URL:

https://app.rankley.com/api/v1/accounts

Authentication

Rankley uses API key authentication.

All requests must include the following HTTP header:

Authorization: Bearer YOUR_API_KEY

Example request:

curl "https://app.rankley.com/api/v1/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Generating an API key in Rankley

To generate an API key:

Log into Rankley.
Click your profile menu in the top-right corner.
Click Integrations.
Scroll down to Organization Integrations.
Find Zapier and click Manage.
Click Generate Key.
Copy the API key.

Important: The full API key is only shown once. Copy and store it securely before closing the modal.

Timestamp format

Rankley returns timestamps in ISO-8601 format with timezone.

Example:

2026-03-01T02:17:44.715Z

Zapier requires timezone-aware timestamps for polling triggers.

Recommended format:

YYYY-MM-DDTHH:mm:ss.sssZ

Valid examples:

2026-02-28T21:17:44.645Z
2026-03-01T02:17:44.715Z

Avoid timestamps without timezone information:

2026-03-01T02:17:44.715

Polling behavior

Rankley’s Zapier triggers use polling endpoints.

Polling endpoints should return:

An array of records
Newest records first
Stable id values for Zapier deduplication
Empty array [] when no records are available

Example empty response:

[]

Endpoint: New Account Created

Used by the Zapier New Account Created trigger.

This trigger returns newly created Rankley account events.

Request

GET /api/v1/account_events?limit=5

Optional `since` parameter

GET /api/v1/account_events?limit=5&since=2026-03-01T00:00:00.000Z

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Number of records to return
`since`	No	ISO-8601 timestamp	Return events after this timestamp

Example request

curl "https://app.rankley.com/api/v1/account_events?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example request with since:

curl "https://app.rankley.com/api/v1/account_events?limit=5&since=2026-03-01T00:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

[
  {
    "id": "acct_11111111-1111-1111-1111-111111111111_2026-01-01T12:00:00.000Z",
    "event_id": "acct_11111111-1111-1111-1111-111111111111_2026-01-01T12:00:00.000Z",
    "event_type": "account_created",
    "created_at": "2026-02-28T11:47:10.112Z",
    "account_id": "11111111-1111-1111-1111-111111111111",
    "account_name": "Example Roofing Co",
    "account_website": "https://www.example-roofing.com/",
    "account_industry": "Roofing Contractor",
    "account_city": "Austin",
    "account_state": "TX",
    "account_phone": "512-555-0100",
    "contact_id": "22222222-2222-2222-2222-222222222222",
    "contact_name": "John Smith",
    "contact_email": "[email protected]",
    "contact_phone": "",
    "account": {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Example Roofing Co",
      "website": "https://www.example-roofing.com/",
      "industry": "Roofing Contractor",
      "city": "Austin",
      "state": "TX",
      "phone": "512-555-0100"
    },
    "best_contact": {
      "contact_id": "22222222-2222-2222-2222-222222222222",
      "contact_name": "John Smith",
      "email": "[email protected]",
      "phone": "512-555-0199"
    }
  }
]

Field descriptions

Field	Type	Description
`id`	string	Unique event ID used by Zapier for deduplication
`event_id`	string	Same event ID, included for compatibility
`event_type`	string	Event type, usually `account_created`
`created_at`	string	Event creation timestamp in ISO-8601 format with timezone
`account_id`	string	Rankley account ID
`account_name`	string	Account or business name
`account_website`	string	Business website URL
`account_industry`	string	Business industry/category
`account_city`	string	Business city
`account_state`	string	Business state
`account_phone`	string	Business phone number
`contact_id`	string	Best contact ID, when available
`contact_name`	string	Best contact name, when available
`contact_email`	string	Best contact email, when available
`contact_phone`	string	Best contact phone, when available
`account`	object	Nested account object
`best_contact`	object or null	Best available contact for the account

Notes on `best_contact`

If an account has contact data, Rankley returns a best_contact object.

The best contact may be selected based on:

Primary contact status
Most complete contact profile
Highest confidence available contact

If no contact is available, best_contact may be null.

Endpoint: New Report Completed

Used by the Zapier New Report Completed trigger.

This trigger returns completed Rankley report events.

Request

GET /api/v1/report_events?limit=5

Optional `since` parameter

GET /api/v1/report_events?limit=5&since=2026-03-01T00:00:00.000Z

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Number of records to return
`since`	No	ISO-8601 timestamp	Return events after this timestamp

Example request

curl "https://app.rankley.com/api/v1/report_events?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example request with since:

curl "https://app.rankley.com/api/v1/report_events?limit=5&since=2026-03-01T00:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

[
  {
    "id": "22222222-2222-2222-2222-222222222222",
    "account_id": "11111111-1111-1111-1111-111111111111",
    "account_name": "KidMed",
    "status": "completed",
    "type": "website + gbp",
    "overall_score": 95,
    "report_url": "",
    "run_at": "2026-02-28T21:17:44.645Z",
    "created_at": "2026-03-01T02:17:44.715Z",
    "updated_at": "2026-03-01T02:17:44.715Z"
  }
]

Field descriptions

Field	Type	Description
`id`	string	Unique report event ID used by Zapier for deduplication
`account_id`	string	Rankley account ID
`account_name`	string	Account or business name
`status`	string	Report status, usually `completed`
`type`	string	Report type, such as `website`, `gbp`, or `website + gbp`
`overall_score`	integer	Overall report score
`report_url`	string	URL for the report; may be blank if unavailable
`run_at`	string	Time the report ran
`created_at`	string	Event creation timestamp
`updated_at`	string	Event update timestamp

Important: `overall_score` must be an integer

Zapier validates field types using sample and live trigger data.

The overall_score value must be returned as an integer.

Correct:

{
  "overall_score": 95
}

Incorrect:

{
  "overall_score": "95"
}

Notes on `report_url`

The report_url field is returned as a string.

In some cases, it may be an empty string if a shareable report URL is not available yet.

Example:

{
  "report_url": ""
}

Endpoint: Accounts

Used for account selection fields in Zapier.

This endpoint helps Zapier display Rankley accounts when a user needs to choose which account a Zap should operate on.

Request

GET /api/v1/accounts

Example request

curl "https://app.rankley.com/api/v1/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Default response

The default response is intentionally minimal for Zapier compatibility.

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Zapier Test Account"
  }
]

Field descriptions

Field	Type	Description
`id`	string	Rankley account ID
`name`	string	Rankley account name

Optional include: best contact

To include contact information:

GET /api/v1/accounts?include=best_contact

Example request:

curl "https://app.rankley.com/api/v1/accounts?include=best_contact" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response:

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Zapier Test Account",
    "best_contact": {
      "contact_id": "22222222-2222-2222-2222-222222222222",
      "contact_name": "John Smith",
      "email": "[email protected]",
      "phone": "512-555-0199"
    },
    "contact_email": "[email protected]",
    "contact_phone": "512-555-0199"
  }
]

Why the default account response is minimal

Zapier account selection fields work best when the response shape is simple:

[
  {
    "id": "account_id",
    "name": "Account Name"
  }
]

For this reason, GET /api/v1/accounts returns only id and name by default.

Additional fields are available through the optional include=best_contact query parameter.

Error responses

Rankley uses standard HTTP status codes.

401 Unauthorized

The API key is missing or invalid.

Common causes:

Missing Authorization header
Invalid API key
API key copied incorrectly

Fix:

Authorization: Bearer YOUR_API_KEY

403 Forbidden

The API key is valid, but access is not allowed.

Common causes:

The API key belongs to a different workspace
The organization does not have access to the requested resource
Permission or plan restrictions

404 Not Found

The endpoint path is incorrect.

Common causes:

Missing /api/v1/
Typo in the endpoint path
Requesting an unsupported endpoint

Correct:

https://app.rankley.com/api/v1/accounts

Incorrect:

https://app.rankley.com/accounts

400 / 422 Validation error

The request contains invalid parameters.

Common causes:

Malformed since timestamp
Invalid query parameter
Unsupported value

Example valid timestamp:

2026-03-01T00:00:00.000Z

429 Rate limited

Too many requests were made in a short period.

Recommended behavior:

Retry after a delay
Use exponential backoff
Avoid aggressive polling outside Zapier’s normal polling behavior

5xx Server error

A temporary Rankley server error occurred.

Recommended behavior:

Retry the request
Contact Rankley support if the issue persists

Data privacy and PII

Rankley API responses may include limited contact data, including:

Contact name
Contact email
Contact phone

Rankley does not log PII in API logs.

All API requests should be made over HTTPS.

Do not share API keys or API responses publicly.

Versioning

Current API version:

v1

All endpoints are under:

/api/v1/

Forward compatibility notes:

New fields may be added over time
Existing field meanings should remain stable within v1
API consumers should safely ignore unknown fields

Zapier reviewer test instructions

Use the following steps to generate live test data for the Rankley Zapier integration.

Create an API key

Log into Rankley.
Click your profile menu in the top-right corner.
Click Integrations.
Scroll down to Organization Integrations.
Find Zapier and click Manage.
Click Generate Key.
Copy the API key.

The full API key is only shown once.

Use this API key to connect Rankley in Zapier.

Generate a New Account Created event

Navigate to Accounts.
Click Add Account.
Select Add via Google Maps URL.

Paste this example business URL:

https://www.google.com/maps/place/Noodle+Blvd/@35.7631046,-78.747035,17z/data=!3m1!4b1!4m6!3m5!1s0x89acf3b7bbe234fb:0x3ef1f4bace8be93c!8m2!3d35.7631046!4d-78.747035!16s%2Fg%2F11cmxwlq2p?entry=ttu&g_ep=EgoyMDI2MDMwMi4wIKXMDSoASAFQAw%3D%3D

Click Use this URL.
Add a contact:
- Name: Test Contact
- Email: [email protected]
Click Create Account.

This will trigger New Account Created.

Alternative account setup

If Google Maps import fails:

Go to Accounts.
Click Add Account.
Select Add Manually.
Enter example business information.
Click Create Account.

This will also trigger New Account Created.

Generate a New Report Completed event

Click Accounts.
Open the account named Zapier Test Account.
Click Run New Report.
Select Website as the only module.
Click Run Now.
Wait for the report to complete.

Once the report finishes, Zapier will detect New Report Completed.

Google Business Profile is not required for a Website-only audit.

Support

For support, contact Rankley from inside the app.

Please include:

Endpoint called
Approximate timestamp of the issue
HTTP status code
Zapier trigger being tested
Organization or workspace name
Any visible request ID or error message, if available

Rankley API Documentation for Zapier

Overview

Base URL

Authentication

Generating an API key in Rankley

Timestamp format

Polling behavior

Endpoint: New Account Created

Request

Optional since parameter

Query parameters

Example request

Example response

Field descriptions

Notes on best_contact

Endpoint: New Report Completed

Request

Optional since parameter

Query parameters

Example request

Example response

Field descriptions

Important: overall_score must be an integer

Notes on report_url

Endpoint: Accounts

Request

Example request

Default response

Field descriptions

Optional include: best contact

Why the default account response is minimal

Error responses

401 Unauthorized

403 Forbidden

404 Not Found

400 / 422 Validation error

429 Rate limited

5xx Server error

Data privacy and PII

Versioning

Zapier reviewer test instructions

Create an API key

Generate a New Account Created event

Alternative account setup

Generate a New Report Completed event

Support

Optional `since` parameter

Notes on `best_contact`

Optional `since` parameter

Important: `overall_score` must be an integer

Notes on `report_url`