Skip to main content

​
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

  1. Navigate to Settings in your Reevo workspace
  2. Go to the API Keys section → New API key button Reevo Integration With Other Tools API Keys Location Pn
  3. Give your key a descriptive name (for example, “Clay Integration” or “Zapier Webhook”)
  4. Select the permissions your integration needs:
    PermissionsReadWrite
    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.
  1. 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:
  1. Find the key in your API keys table
  2. Click the three-dot menu next to the key
  3. Select Expire key
  4. The key will immediately stop working and show as “Expired” in your table

​
Using Your API Key

In your external tool, configure Webhooks by:
  1. 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.
  2. Set your request details
    • Endpoint: See available endpoints below.
    • Query Parameter:
      • Key: payload_type
      • Value: json
  3. Define the body of your request. See example requests and supported values for each endpoint below:
    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": "[[email protected]](<mailto:[email protected]>)",
	"contact_owner_email": "[[email protected]](<mailto:[email protected]>)",
	"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"}
}'
    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": "[email protected]",
    "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"
    }
  }'
    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": "[email protected]",
  "contact_custom_fields": {"Your_Custom_Field_API_Name_1": "Your Value"}
      }


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


    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":"[email protected]","custom_fields":null}]%
    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_user_id": "str",
    "primary_contact_id": "str",
    "amount": d=Decimal
    "pipeline_name": "str",
    "custom_fields": {
      "deal_source": "Inbound",
      "probability": "75%"
    }
  }'
    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/>" \curl -X GET "https://api.reevo.ai/api/v1/public/opportunities/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API LE"
  -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%",    
    }
  }'


    curl -X GET "<https://api.reevo.ai/api/v1/public/opportunities/>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: Your API LE"
    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"
  }'
    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": "[[email protected]](<mailto:[email protected]>)m",
    "type": "REMINDER"
  }'
    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": "[[email protected]](<mailto:[email protected]>)m"
  }'
    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": "[[email protected]](<mailto:[email protected]>)m"}'
    Enroll contact in sequence with owner’s mailbox address
    contact_email: EmailStr*
sequence_id: UUID*
mailbox_email: EmailStr # if not provided will default to round-robin
    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": "[[email protected]](<mailto:[email protected]>)m", "sequence_id": "UUID", "mailbox_email": "[[email protected]](<mailto:[email protected]>)m"}'
    • 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 Integration W Other Tools Custom Fields Pn
    • 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
    {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"contact_custom_fields": {
	"cus_field__Lead_Source": "inbound_form",
	"cus_field__Lead_Source_Details": "board member"
}
}
  4. Publish and run the test to confirm the data is correctly sent to Reevo

​
Troubleshooting / FAQs

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.
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.
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.
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.
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.
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? Reach out to our support team here