Async Results - Pipecorn API Documentation

Some of our endpoints are asynchronous: they answer immediately while the work continues in the background. This is common for operations that take longer to complete, such as contact enrichment or search extraction.

How it works

Asynchronous enrichment answers immediately with a Location header, also returned as status_url in the body: the URL that holds the result.

HTTP/1.1 200 OK
Location: https://app.pipecorn.com/api/v2/contacts/550e8400-e29b-41d4-a716-446655440000

{
  "enrichment_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Mathieu",
  "last_name": "Brun-Picard",
  "status": "pending",
  "status_url": "https://app.pipecorn.com/api/v2/contacts/550e8400-e29b-41d4-a716-446655440000"
}

There are two ways to get the result:

Polling Method

Make a request to an async endpoint
Read the status URL from the Location header
Poll it until status is finished, backing off between calls (start at 2 seconds, cap at 30)
Read the result from the same response

Status lookups are exempt from the plan rate limit, so polling never uses up your quota.

Webhook Method

Make a request to an async endpoint with a webhook_url
Keep the enrichment_id from the response
Continue your application flow
Receive results automatically via webhook when the job completes

In order to avoid unnecessary load on our servers, we suggest using the webhook method.

Endpoints

Endpoint	Status URL
`POST /contacts/single_enrich`	`Location` header and `status_url`: `GET /contacts/{id}`
`POST /leads`	`GET /searches/{id}`
`POST /accounts`	`GET /lists/{id}`