Formatting your Data - API

Overview

ReviveAI's API allows you to send lead and contact data directly into the platform in real time — removing the need for manual exports and enabling seamless integration with your CRM, middleware, or data pipeline.

Because every client setup is configured specifically for your data structure and use case, the first step is always to arrange an onboarding call with your ReviveAI contact. During this call we will:

• Map your data fields to ReviveAI's expected payload format
• Align on data standards (date formats, phone number formats, custom fields)
• Provision your test and live endpoint credentials
• Confirm encryption and authentication requirements

For information on encryption standards, please refer to our Security Statements.

Authentication

All requests to the ReviveAI API must be authenticated using a Bearer Token passed in the request header.

API tokens are provisioned per client and environment (test and live tokens are separate). Tokens are delivered via a secure one-time-secret provider — they will not be shared over email or standard messaging channels.

Keep your token secure. Do not commit it to version control or share it publicly. If you believe a token has been compromised, contact [email protected] immediately for a replacement.

Endpoint

All lead data should be submitted via a POST request to your provisioned endpoint. Endpoints are unique per client and environment.

You will receive your specific endpoint URL during the onboarding call.

Headers

Payload Data

The payload is a JSON object containing the lead or contact record. The core fields are listed below — additional custom fields will be agreed during your onboarding call and documented in your client-specific field mapping.

Phone number formatting: All numbers must be submitted in E.164 format. ReviveAI will run validation and cleansing on ingestion, but correctly formatted numbers will process faster and more reliably. See Number Validation & Data Cleansing for more detail.

Example Payload

{
  "first_name": "John",
  "last_name": "Test",
  "phone_number": "+447701234567",
  "email": "[email protected]",
  "lead_ref": "CRM-REF-00123",
  "application_date": "2024-10-12T13:36:00Z"
}

Response Codes

ReviveAI returns standard HTTP status codes on each request.

Example Success Response

{
  "status": "success",
  "lead_ref": "CRM-REF-00123",
  "message": "Lead received and queued for processing"
}

Example Error Response

{
  "status": "error",
  "code": 400,
  "message": "Missing required field: phone_number"
}

Data Returned to Your System

Once ReviveAI has processed a lead and the AI agent has completed its engagement journey, outcome data is returned to your system using the lead_ref you supplied as the unique identifier.

The data returned will depend on your configuration, but typically includes:

The method by which this data is returned (webhook POST, CRM write-back, or API pull) is agreed during your onboarding and documented in your field mapping. See Configured Field Mapping for more detail.

Number Validation on Ingestion

All phone numbers submitted via the API are automatically run through ReviveAI's validation pipeline before outreach begins. This includes:

• Format normalisation to E.164 standard
• Carrier lookup (mobile vs. landline)
• Risk scoring (VOIP, spam traps, unreachable numbers)
• Duplicate detection

Invalid or unroutable numbers are flagged and suppressed from outreach. You will receive a report of any records that were excluded. See Number Validation & Data Cleansing for full details.

Test & Live Environments

ReviveAI operates separate test and live environments. Both use the same payload format and authentication method, with different endpoint URLs and tokens.

Test Environment

Use the test environment to:

• Validate your payload structure and field formatting
• Confirm your authentication is working correctly
• Review how records are received and processed before going live

Your ReviveAI contact will provide the test endpoint and token before any live data is transferred.

Live Environment

Once the test transfer has been reviewed and signed off, you will be issued your live endpoint and token via the same secure provisioning process.

Test and live tokens are not interchangeable. Submitting live data to the test endpoint will result in records being processed in a sandboxed environment only.

Rate Limits

Rate limits are applied per client and environment. Standard limits are:

If your use case requires higher throughput, speak to your ReviveAI contact to discuss a custom limit.

Requests that exceed the rate limit will receive a 429 response. Implement an exponential backoff strategy to handle this gracefully.

Custom Fields

If your lead data includes fields beyond the standard payload — such as product interest, source, loan amount, or policy type — these will be agreed and mapped during your onboarding call. Custom fields follow the same formatting conventions (snake_case keys, JSON values) and are documented in your client-specific configuration.

Next Steps

• Arrange your onboarding call to map fields and confirm your data format
• Receive your test credentials — endpoint URL and API token via secure link
• Submit a test payload and confirm receipt with your ReviveAI contact
• Receive your live credentials once the test transfer is approved
• Go live

For any questions on setup or integration, contact [email protected] or speak to your customer success manager.