Overview

Reevo provides API keys that allow you to connect external tools and automate data flow into your workspace. With API keys, you can push contacts from platforms like Clay or Zapier, build custom integrations, or sync data from your own systems directly into Reevo without manual entry. API keys use a permission-based system, allowing you to control exactly what each key can access. This means you can create separate keys for different integrations with only the permissions they need.

Prerequisites

You must be an admin in your Reevo workspace to create API keys
Your organization must have available quota for public requests

Watch: How to Generate and Manage API Keys

Step-by-Step Instructions

Creating a New API Key

Navigate to Settings in your Reevo workspace
Go to the API Keys section → New API key button
Give your key a descriptive name (for example, “Clay Integration” or “Zapier Webhook”)
Select the permissions your integration needs:
Permissions Read Write
Accounts ✓ ✓
Contacts ✓ ✓
Opportunities ✓ ✓
Tasks ✓ ✓
Users ✓ X
Mailbox ✓ X
Sequence Enrollment ✓ ✓
Webhooks ✓ ✓

Permissions	Read	Write
Accounts	✓	✓
Contacts	✓	✓
Opportunities	✓	✓
Tasks	✓	✓
Users	✓	X
Mailbox	✓	X
Sequence Enrollment	✓	✓
Webhooks	✓	✓

Read permissions allow an API key to view and retrieve data, but not modify it. For example, with Accounts Read, you can fetch account information but cannot create or update accounts.Write permissions allow an API key to create, update, or modify data. Importantly, write permissions automatically include read permissions for the same resource. So if you have Contacts Write, you can both read and write contact data without needing to also select Contacts Read.

Click Generate

Important: Copy the API key immediately and store it securely. You will not be able to view it again after closing the popup.

Managing Existing API Keys

You can manage Existing API Keys under Setting → Integrations. The API keys table shows:

Name: The label you gave the key
Permissions: What the key can access
Status: Whether the key is Active or Expired

Active keys are listed first, followed by expired keys, sorted alphabetically by name.

Expiring an API Key

If you need to revoke access for a key:

Find the key in your API keys table
Click the three-dot menu next to the key
Select Expire key
The key will immediately stop working and show as “Expired” in your table

Using Your API Key

In your external tool, configure Webhooks by:

Assigning a new HTTP API and include your API key in the request header:
- Header name: x-api-key
- Header value: Your API key
The system automatically validates that your key has the required permissions for each request. If a key lacks necessary permissions, the request will be rejected with a clear error message indicating which permissions are missing.
Set your request details
- Endpoint: See available endpoints below.
- Query Parameter:
  - Key: payload_type
  - Value: json

Define the body of your request. See example requests and supported values for each endpoint below:

Account Contact

This does upsert for account and contact.Supported values:

    email: str*
    first_name: str | None = None
    last_name: str | None = None
    middle_name: str | None = None
    phone_number: str | None = None
    company: str | None = None
    title: str | None = None
    department: str | None = None
    contact_linkedin_url: str | None = None
    contact_facebook_url: str | None = None
    contact_zoominfo_url: str | None = None
    contact_x_url: str | None = None
    contact_owner_email: str | None = None
    account_linkedin_url: str | None = None
    account_facebook_url: str | None = None
    account_zoominfo_url: str | None = None
    account_x_url: str | None = None
    account_owner_email: str | None = None
    account_website: str | None = None
    account_custom_fields: dict[UUID | str, str | list[str]] | None = None
    contact_custom_fields: dict[UUID | str, str | list[str]] | None = None

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/account_contact>" \
	-H "Content-Type: application/json" \
	-H "X-Api-Key: Your API KEY" \
	-d '{
	"email": "[postcon@postman.com](<mailto:postcon@postman.com>)",
	"contact_owner_email": "[john.doe@acme.com](<mailto:john.doe@acme.com>)",
	"account_website": "[<https://www.acme.com>](<https://www.acme.com/>)",
	"account_linkedin_url": "<https://linkedin.com/company/acme-corp>",
	"account_facebook_url": "<https://facebook.com/acmecorp>",
	"account_zoominfo_url": "<https://zoominfo.com/c/acme-corporation>",
	"account_x_url": "<https://twitter.com/acmecorp>",
	"contact_custom_fields": {"Your_Custom_Field_API_Name_1": "Your Value"},
	"account_custom_fields": {"Your_Custom_Field_API_Name_2": "Your Value"}
}'

Accounts

Create

Supported values:

    name: str*
    owner_email: str | None = None
    official_website: str | None = None
    linkedin_url: str | None = None
    facebook_url: str | None = None
    zoominfo_url: str | None = None
    x_url: str | None = None
    custom_fields | dict[UUID | str, str | list[str]] | None = None

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/accounts/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API KEY" \
  -d '{
    "name": "Acme Corporation",
    "owner_email": "john.doe@acme.com",
    "official_website": "<https://www.acme.com>",
    "linkedin_url": "<https://linkedin.com/company/acme-corp>",
    "facebook_url": "<https://facebook.com/acmecorp>",
    "zoominfo_url": "<https://zoominfo.com/c/acme-corporation>",
    "x_url": "<https://twitter.com/acmecorp>",
    "custom_fields": {
      "industry": "Technology",
      "employee_count": "500-1000"
    }
  }'

Update

Supported values:

    name: str | None = None
    owner_email: str | None = None
    official_website: str | None = None
    linkedin_url: str | None = None
    facebook_url: str | None = None
    zoominfo_url: str | None = None
    x_url: str | None = None
    custom_fields | dict[UUID | str, str | list[str]] | None = None

Example full request:

curl -X PATCH "<https://api.reevo.ai/api/v1/public/accounts/>" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: Your API KEY" \
  -d '{
  "email": "postcon@postman.com",
  "contact_custom_fields": {"Your_Custom_Field_API_Name_1": "Your Value"}
      }

Get By ID

curl -X GET "<https://api.reevo.ai/api/v1/public/accounts/Account UUID>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key"

Search by domain name (contains)

curl -X POST "<https://api.reevo.ai/api/v1/public/accounts/search>" \
  -H "X-Api-Key: Your API KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "getaida.com"}'

Example Respond:

[{"id":"UID","name":"GETAIDA","status":"CUSTOMER","official_website":"getaida.com","linkedin_url":"https:\\/\\/www.linkedin.com\\/company\\/getida","facebook_url":null,"zoominfo_url":null,"x_url":null,"owner_email":"zvtestabc@gmail.com","custom_fields":null}]%

Opportunities

Create

Supported values:

    display_name: str*
    account_id: UUID*
    owner_email: str | None = None
    primary_contact_email: str | None = None
    amount: Decimal | None = None
    pipeline_name: str | None = None
    custom_fields | dict[UUID | str, str | list[str]] | None = None

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/opportunities/>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key" \
  -d '{
    "display_name": "Enterprise Software Deal",
    "account_id": "UUID*",
    "owner_email": "str",
    "primary_contact_email": "str",
    "amount": d=Decimal
    "pipeline_name": "str",
    "custom_fields": {
      "deal_source": "Inbound",
      "probability": "75%"
    }
  }'

Update

Supported values:

    display_name: str | None = None
    account_id: UUID | None = None
    owner_email: str | None = None
    primary_contact_email: str | None = None
    additional_contact_emails: list[str] | None = None
    amount: Decimal | None = None
    next_step_details: str | None = None
    next_step_due_at: ZoneRequiredDateTime | None = None

Example full request:

curl -X PATCH "https://api.reevo.ai/api/v1/public/opportunities/UUID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key" \
  -d '{
    "amount": 95000.00,
    "next_step_details": "Send final proposal and contract for review",
    "next_step_due_at": "2024-02-20T10:00:00Z",
    "custom_fields": {
      "deal_stage": "Proposal Sent",
      "probability": "90%",    
    }
  }'

Get By ID

curl -X GET "<https://api.reevo.ai/api/v1/public/opportunities/UUID>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API KEY"

Supported values:

display_name: str | None = None
account_id: UUID | None = None
owner_user_email: UUID | None = None
status: PipelineStatus | None = None
stage_name: str | None = None

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/opportunities/search>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API KEY" \
  -d '{"account_id": "UUID"}'

Shift Stage

Supported Values:

 target_stage_name: str*
 closed_reason_names: list[str] | None
 closed_reason_custom_detail: str | None

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/opportunities/>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key" \
  -d '{
    "target_stage_name": "Qualified"
  }'

Tasks

Supported values:

    title: str*
		owner_email: EmailStr*
    status: TaskStatus (default=TaskStatus.OPEN)
    priority: TaskPriority(default=TaskPriority.MEDIUM)
    type: TaskType(default=TaskType.REMINDER)
    due_at: ZoneRequiredDateTime
    note: str | None
    account_id: UUID | None
    contact_emails: list[EmailStr] | None
    opportunity_name: str | None

Example full request:

curl -X POST <https://api.reevo.ai/api/v1/public/tasks> \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key" \
  -d '{
    "title": "Create Task API Test",
    "owner_email": "[john.doe@acme.com](<mailto:john.doe@acme.com>)",
    "type": "REMINDER"
  }'

Users

Search organization user via email

email: EmailStr*

Example full request:

curl -X POST <https://api.reevo.ai/api/v1/public/users/search> \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API KEY" \
  -d '{
    "email": "[john.doe@acme.com](<mailto:john.doe@acme.com>)"
  }'

Mailboxes

Search mailboxes via email

owner_user_email: EmailStr*

Example full request:

curl -X POST "<https://api.reevo.ai/api/v1/public/mailboxes/search>" \
-H "X-Api-Key: Your API KEY" \
-H "Content-Type: application/json" \
-d '{"owner_user_email": "johndoe@acme.com"}'

Sequences Enrollments

Enroll a single contact into a sequence. One contact per API request.Supported values:

contact_email: EmailStr*
sequence_id: UUID*
mailbox_email: EmailStr | None  # Optional — see mailbox behavior below

Mailbox behavior:

If mailbox_email is provided, that specific mailbox will be used to send emails for this enrollment.
If mailbox_email is omitted, Reevo defaults to a random mailbox from the contact’s CRM owner’s available mailboxes.

The API supports one contact per request. For bulk enrollment, use the Sequences UI.

Example full request:

curl -X POST "https://api.reevo.ai/api/v1/public/sequence_enrollments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API Key" \
  -d '{
    "contact_email": "jane.doe@prospect.com",
    "sequence_id": "your-sequence-uuid",
    "mailbox_email": "sender@yourcompany.com"
  }'

Custom Fields

First create the field in Reevo. Refer to this article to learn how to create custom fields.
To find your custom field’s API name, go to settings where the custom field was created and hover over the field
In the JSON body, use:

"contact_custom_fields": {
	"Your_Custom_Field_API_Name_1": "Your Value",
	"Your_Custom_Field_API_Name_2": "Your Value"}
"account_custom_fields": {
	"Your_Custom_Field_API_Name_1": "Your Value",
	"Your_Custom_Field_API_Name_2": "Your Value"}

Example Pull

{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@acme.co",
"contact_custom_fields": {
	"cus_field__Lead_Source": "inbound_form",
	"cus_field__Lead_Source_Details": "board member"
}
}

Account and Contact Retrieval

# Must provide exact match of one of the below fields:
 contact_email: str | None = None
 account_domain: str | None = None
 contact_phone_number: str | None = None

curl -X GET \
  "https://api.reevo.ai/api/v1/public/account_and_contact_retrieval?contact_email=jon@acme.com" \
  -H "X-Api-Key: Your API Key"
  
  or
  
curl -X GET \
  "https://api.reevo.ai/api/v1/public/account_and_contact_retrieval?contact_phone_number=%2B141512345678#" \
  -H "X-Api-Key: Your API Key"

For phone numbers, 2B represents the ”+” sign. Follow this by an area code. Final output example: 2B141512345678 = +1 (415) 123-45678.

Publish and run the test to confirm the data is correctly sent to Reevo

Troubleshooting / FAQs

Why can't I create an API key?

Only workspace admins can create API keys. If you need access, ask an admin to either grant you admin permissions or create the key for you.

I lost my API key. Can I retrieve it?

No. For security reasons, API keys are only shown once when created. If you lose a key, you must expire the old one and generate a new one.

What happens if I use an expired key?

Requests using an expired key will be rejected with an “API key has expired” error. You’ll need to generate a new key and update your integration.

Can I use one API key for multiple integrations?

Yes, as long as the key has all the permissions needed by each integration. However, for better security and tracking, consider creating separate keys for each integration.

What does "write permission grants read permission" mean?

If your key has write access to a resource (like Contacts Write), it automatically includes read access too (Contacts Read). You don’t need to select both.

I'm seeing a quota warning. What does that mean?

Your organization has limits on public requests. If you’re approaching or exceeding your quota, contact your account manager to discuss increasing your limits.

Still have questions? Sign in and use AskReevo for instant answers or to raise a support ticket.

Getting Started

Product Releases

Data Management & Migration

CRM Configurations

Domains & Mailboxes

Conversations

Prospecting & Outreach

AI & Productivity

Opportunity Products and Deal Management

Analytics & Reporting

Automations & Workflows

Admin & Security

API Integrations with Other Tools

Overview

Prerequisites

Watch: How to Generate and Manage API Keys

Step-by-Step Instructions

Creating a New API Key

Managing Existing API Keys

Expiring an API Key

Using Your API Key

Troubleshooting / FAQs

Getting Started

Product Releases

Data Management & Migration

CRM Configurations

Domains & Mailboxes

Conversations

Prospecting & Outreach

AI & Productivity

Opportunity Products and Deal Management

Analytics & Reporting

Automations & Workflows

Admin & Security

​Overview

​Prerequisites

​Watch: How to Generate and Manage API Keys

​Step-by-Step Instructions

​Creating a New API Key

​Managing Existing API Keys

​Expiring an API Key

​Using Your API Key

​Troubleshooting / FAQs

Overview

Prerequisites

Watch: How to Generate and Manage API Keys

Step-by-Step Instructions

Creating a New API Key

Managing Existing API Keys

Expiring an API Key

Using Your API Key

Troubleshooting / FAQs