Background
Angi’s Lead Integration API is an event-based API that distributes new customer leads to a defined endpoint in a JSON data format as they occur in real time. The reference documentation included here provides everything our partners need to know to facilitate integration with their CRM or preferred applications.
Partner Requirements
The following requirements are to be met by the partner in order to facilitate integration.
Headers Sent by Angi
Angi will send the following headers with each lead post request:
● Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
● Content-Type: application/json
● x-api-key: [Your-Provided-API-Key] (This header is only sent if an API key is provided by the partner for authentication)
Important Note on Headers: Angi does not currently send a User-Agent header and cannot customize request headers beyond those listed above. Partners should design their endpoints to accept requests with the specified headers.
Authentication
Angi supports API key-based authentication for securing lead posts to your endpoint.
● Method: If authentication is required, Angi will include a partner-provided API key in the request header.
● Header Name: x-api-key
● Key Length: The API key has a maximum length of 160 characters.
● Setup: Partners must provide their API key to their Angi contact for configuration in our System.
Note on Authentication: Currently, the only supported authentication mechanism is via an x-api-key header.
Endpoints
Production Endpoint | Define a secure production endpoint for Angi to post new, live leads to. |
Testing Endpoint (Optional, but recommended) | Define a secure endpoint for Angi to post test leads to for testing integration. |
Response Handling
Your endpoint must be configured to handle incoming JSON POST requests from Angi.
Response Code
Return an HTTP 200 OK status code to acknowledge successful receipt and acceptance of the lead data.
Response Body (JSON Format)
Responses MUST be in JSON format. Non-JSON responses, or responses without a 200 OK status, may be interpreted as a delivery failure by Angi's system.
The JSON response body should indicate success. While a detailed body is not strictly required for a success acknowledgement, a simple JSON object is expected.
Example of a minimal successful response:
{ "status": "success"}
Example of a successful response with more detail (optional):
{ "status": "success", "message": "Lead successfully received", "leadId": "12345" // (Optional: if you want to include the ID you've processed)}
Processing Time: Respond promptly to lead posts. Ideally, within 2-5 seconds. Prolonged processing should be handled asynchronously after sending the 200 OK acknowledgement.
Error Handling
In the event an error occurs, Angi will retry delivering a lead up to 3 times in 15 minute intervals.
Example error events can include:
● A response code other than 200 is returned to Angi.
● A response code of 200 with a non-JSON response body, or a JSON response that
doesn't contain a status field indicating success (e.g. missing status field or status value not set to "success").
● A server timeout.
Model
Lead Post Request
Name | Data Type | Included | Notes |
name | String | Always | Homeowner full name |
firstName | String | Sometimes | Homeowner first name |
lastName | String | Sometimes | Homeowner last name |
address | String | Always | Homeowner address |
city | String | Always | Homeowner city |
stateProvince | String | Always | Homeowner state code |
postalCode | String | Always | Homeowner zip |
primaryPhone | String | Always | Homeowner primary phone |
phoneExt | String | Sometimes | Homeowner primary phone extension |
secondaryPhone | String | Sometimes | Homeowner secondary phone |
secondaryPhoneExt | String | Sometimes | Homeowner secondary phone extension |
String | Always | Homeowner email | |
srOid | Integer | Always | Unique service request ID |
leadOid | Integer | Always | Unique lead ID |
fee | BigDecimal | Always | Lead fee |
taskName | String | Always | Task name of service requested |
comments | String | Always | Homeowner provided comments about the service requested |
matchType | String | Always | Description of the match |
leadDescription | String | Always | Description of the type of lead |
spEntityId | Integer | Sometimes | Unique identifier for the pro’s business on Angi |
spCompanyName | String | Always | Pro’s business name on Angi |
contactStatus | String | Sometimes | Contact status of the lead if Angi’s advisors tried to contact them |
crmKey | String | Sometimes | Optional, unique identifier defined by the pro for routing |
leadSource | String | Sometimes | Source of the lead |
trustedFormURL | String | Sometimes | URL for the TrustedForm certificate |
interview | Array | Sometimes | Array of questions and answers, provided by the homeowner, related to the service requested |
interview.question | String | Sometimes | Questions presented to the homeowner |
interview.answer | String | Sometimes | Answers provided by the homeowner |
automatedContactCompliant | Boolean | Always | Indicates whether consent is given to use automated messaging when contacting HO |
automatedContactConsentId | String | Sometimes | An ID to reference the specifics of a compliance provided related to automatedContactCompliant |
Post Example
Lead Post Request
{ "name":"Jane Doe" ,"firstName":"Jane" ,"lastName":"Doe" ,"address":"123 Main Street" ,"city":"Denver" ,"stateProvince":"CO" ,"postalCode":"80210" ,"primaryPhone":"3031234567" ,"phoneExt":"1234" ,"secondaryPhone":"3037654321" ,"secondaryPhoneExt":"5678" ,"email":"janedoe@gmail.com" ,"srOid":123456789 ,"leadOid":987654321 ,"fee":25.67 ,"taskName":"Moving Out-of-State" ,"comments":"I am moving my family of 4 to a new state. We have a 3 bedroom house worth of stuff and looking for more information about your moving services." ,"matchType":"Lead" ,"leadDescription":"Standard" ,"spEntityId":12345678 ,"spCompanyName":"Standard Company Name" ,”contactStatus”:”New Appt - Transferred” ,"primaryPhoneDetails": { "maskedNumber": false, } ,”crmKey”:”abcd-12345” ,"leadSource":"HomeAdvisor" ,"trustedFormUrl":"https://cert.trustedform.com/xxz1z51db5ed50eb17992be2686166f4 fc87f11c" ,"automatedContactCompliant":true ,"automatedContactConsentId":"223e4567-e89b-12d3-a456-426614174333" ,"interview":[ {"question":"What type of moving help do you need?"
,"answer":"Out of state"} ,{"question":"When do you want the pro to begin work?" ,"answer":"More than 2 weeks"} ,{"question":"What zip code are you moving to?" ,"answer":"84044"} ,{"question":"What zip code are you moving from?" ,"answer":"80210"} ,{"question":"When is your moving date?" ,"answer":"8/11/2024"} ] } |
Response Example
{ "status":"success" } |