Reworked API Documentation
Welcome to the official Reworked.ai API documentation. Our REST API enables you to integrate lead scoring capabilities directly into your existing systems and workflows, helping you identify high-quality leads and eliminate wasteful spending on low-quality prospects.
The Reworked.ai API provides a secure, reliable way to access our advanced lead scoring technology. Whether you're in solar installation, roofing, real estate investment, or other home services industries, our API helps you programmatically determine which leads deserve your attention and which don't.
BASE URL
Contact your point of contact at Reworked.ai to obtain the base URL
CLIENT LIBRARIES
Generate JWT Tokens
Authentication with the Reworked.ai API is handled through JSON Web Tokens (JWT). This secure authentication method ensures that only authorized applications can access your lead data and our scoring services.
To authenticate with our API:
Generate an API key in your Reworked.ai dashboard
Exchange your API key for a JWT token using the authentication endpoint
Include this token in the authorization header of subsequent requests
The JWT token will be valid for 24 hours, after which you'll need to generate a new one.
ENDPOINT
/generate-token
METHOD
POST
Request Body
When sending leads for scoring, your request body should include all relevant lead information. The more data you provide, the more accurate our scoring will be.
api_key
will be provided by Reworked.
email id you used to create an account on Reworked.ai.
REQUEST BODY
{
"api_key": "api-key",
"email": "abc@gmail.com"
}
Response
The Reworked.ai API returns a structured response.
Status Code
200
The token should be sent as an authorization header in the
process-leads
API
RESPONSE
{
"msg": "Token generated successfully",
"data": {
"token": "Auth Token",
"expires_at": "Timestamp"
}
}
Error Cases
Our API includes comprehensive error handling to help you quickly diagnose and resolve issues during integration.
Status Code
404
CASE 1
{
"msg": "Api key is invalid",
"data": null
}
CASE 2
{
"msg": "Customer data not found",
"data": null
}
Process Leads
The /process-leads endpoint allows authorized users to submit lead data for processing, supporting both file-based and raw JSON input. This API is optimized for handling large datasets and can initiate lead scoring or enrichment workflows tailored to specific industries.
How to Use the /process-leads Endpoint
Authenticate using the
/generate-tokenendpoint to obtain a valid JWT token. This token must be included in theAuthorizationheader of your request.Send a POST request to
/process-leadswith the required payload:At a minimum, include your
emailand specifyinput_typeas either"url"or"json".If using
"url", provide thefile_urlpointing to the dataset you want processed.If using
"json", include theinput_dataas a JSON object.
Optionally, provide additional parameters:
callback_url: to receive a notification once processing is complete.industry_profile_typeorindustry_profile_id: to apply a specific enrichment profile. If both are provided,industry_profile_typetakes precedence.overwrite: to control whether existing data should be replaced.customer_request_id: an external ID to track the request.
File Format Requirements:
If uploading a file, ensure it includes all required columns based on the selected industry profile for successful processing.
What You Receive Upon Submission
A file upload identifier to track your request.
A token for querying the
/file-statusendpoint.A status reflecting the current processing state:
PROCESSINGPROCESSEDERRORUNDERREVIEW
Additional Notes
Duplicate Prevention: The system checks for duplicate file submissions. If a file is already being processed, a message will be returned indicating the duplicate.
Token Expiry: The JWT token used in the
Authorizationheader is valid for 24 hours. After expiration, a new token must be generated.
ENDPOINT
process-leads
METHOD
POST
Headers
Authorization
Authorization Token from generate-token API
response
HEADERS
{
"Authorization": "Authorization Token from generate-token API response"
}
Request Body
When sending leads for scoring, your request body should include all relevant lead information. The more data you provide, the more accurate our scoring will be.
file_url
The URL of the file to process
email id you used to create an account on Reworked.ai.
callback_url
callback_url
REQUEST BODY
{
"file_url": "file upload file url",
"email": "email",
"callback_url": "callback_url",
"overwrite" : true,
"industry_profile_type": "industry_type",
"input_type":"url",
"industry_profile_id": "industry_profile_id",
"customer_request_id":"customer_request_id"
}
REQUIRED COLUMNS IN THE FILE
Response
Response of the /process-leads api
Status Code
200
The token should be sent as an authorization header in the
file-status
API
file_upload_identifier
unique identifier of your request
RESPONSE
{
"msg": "File processing started",
"data": {
"token": "Auth Token to be used in file-status api",
"file_upload_identifier": "file upload identifier",
"status":"PROCESSING"
}
}
Error Cases
Our API includes comprehensive error handling to help you quickly diagnose and resolve issues during integration.
Common error messages:
"Invalid token"- JWT token email doesn't match request email"Invalid industry_profile_type provided. Allowed values are: REAL_ESTATE_INVESTORS, SOLAR_INSTALLER, ROOFING"- When industry_profile_type is invalid
Status Code
400
CASE 1
{
"msg": "Api key is invalid",
"data": null
}
CASE 2
{
"msg": "File url is missing",
"data": null
}
File Status
The /file-status endpoint enables clients to check the current processing state of a previously submitted file.
To use this endpoint:
Include the authorization token received from the
/process-leadsresponse in theAuthorizationheader.Submit a
POSTrequest with thefile_upload_identifier(also from/process-leads) and your email address.
Possible File Processing Statuses
PROCESSING: The file is currently being processed.UNDERREVIEW: Processing is complete but results are undergoing review. Expect completion within 12 hours.PROCESSED: The file has been successfully processed.ERROR: Processing could not be completed due to one or more issues.
ENDPOINT
file-status
METHOD
POST
Headers
Authorization
token from process-leads API response
HEADERS
{
"Authorization": "token from process-leads API response"
}
Request Body
When sending leads for scoring, your request body should include all relevant lead information. The more data you provide, the more accurate our scoring will be.
file_upload_identifier
The unique identifier is obtained
from the process-leads response
email id you used to create an account on Reworked.ai.
REQUEST BODY
{
"file_upload_identifier": "file upload identifier",
"email": "abc@gmail.com" ,
}
Response
Response of the /process-leads api
Status Code
200
file_upload_identifier
unique identifier of your request
RESPONSE
{
"msg": "File is already in process, pls check after sometime",
"data": {
"error_detail"null,
"token": "Auth Token",
"file_upload_identifier": "file upload identifier",
"status":"PROCESSING"
}
}
Response
Response of the /process-leads api
Status Code
200
file_upload_identifier
unique identifier of your request
RESPONSE
{
"msg": "File is under review, it should be processed within the next 12hrs",
"data": {
"error_detail"null,
"token": "Auth Token",
"file_upload_identifier": "file upload identifier",
"status":"UNDERREVIEW"
}
}
Error Cases
Our API includes comprehensive error handling to help you quickly diagnose and resolve issues during integration.
Status Code
401
Status Code
500
CASE 1
{
"msg": "Api key is invalid",
"data": null
}
CASE 2
{
"msg": "Error 103: Requisite columns required to generate a Betty Score is not present. Please contact admin@reworked.ai or call at +1 888 306 1949.",
"data": {
"error_detail":"Error 103: Requisite columns required to generate a Betty Score is not present. Please contact admin@reworked.ai or call at +1 888 306 1949."
"status": "ERROR"
}
}
API Sequence Diagram
Below is the sequence diagram for API interactions:
For bulk scoring operations, our API supports large batches of leads efficiently.
Rate Limit: 50,000 records in a file