API - Recommendations: Fetch Recommendations

Before calling this endpoint, you must first create an ICP using POST /v2/recommendations/icp and pass the same externalUserId here to retrieve matching recommendations.

Endpoint
POST /v2/recommendations/fetch

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "externalUserId": "ext-user-123",
  "pagination": {
    "from": 0,
    "to": 10
  }
}

Fields:

externalUserId — optional string (maximum 255 characters). Pass the same externalUserId used when creating your ICP. If not provided, recommendations associated with the authenticated user will be returned
pagination — required object. Use from and to to page through results

Example Response

{
  "companies": [
    {
      "description": "The connected workspace for sales teams",
      "domain": "surfe.com",
      "employeeCount": 50,
      "hqAddress": "Paris, France",
      "hqCountry": "France",
      "industries": [
        "SaaS",
        "Sales"
      ],
      "keywords": [
        "sales",
        "crm",
        "productivity"
      ],
      "linkedInURL": "https://www.linkedin.com/company/surfe",
      "locations": [
        {
          "country": "France",
          "latitude": 48.8566,
          "locality": "Paris",
          "longitude": 2.3522,
          "postalCode": "75001",
          "primary": true,
          "region": "Ile-de-France",
          "regionCode": "IDF",
          "streetAddress": "1 Rue de Rivoli"
        }
      ],
      "logo": "https://cdn.surfe.com/logo.png",
      "name": "Surfe",
      "people": [
        {
          "country": "US",
          "currentJobDescription": "Leading the sales team at Surfe",
          "departments": [
            "Sales"
          ],
          "firstName": "John",
          "jobTitle": "Head of Sales",
          "lastName": "Doe",
          "linkedinUrl": "https://www.linkedin.com/in/johndoe",
          "location": "New York, US",
          "seniorities": [
            "Head"
          ],
          "summary": "Experienced sales leader with 10+ years"
        }
      ],
      "recommendation": {
        "generatedAt": "2024-05-20T10:00:00Z",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reasons": [
          {
            "description": "This company operates in your target industry",
            "score": 85,
            "shortDescription": "Industry match",
            "title": "Matches your ICP",
            "type": "INDUSTRY_MATCH"
          }
        ]
      },
      "size": "51-200",
      "yearFounded": 2020
    }
  ],
  "pagination": {
    "from": 0,
    "hasMore": true,
    "to": 10
  }
}

Understanding the Response Each company in the response includes:

Full company details including domain, industry, employee count, location and LinkedIn URL
A list of matching people contacts with their job title, department, seniority and LinkedIn URL
A recommendation object explaining why the company was recommended, including a score and reason type

The pagination object in the response includes a hasMore field — if true, there are more results available. Increment your from and to values to fetch the next page.

Important Things to Know

Recommendations are refreshed daily
Results are stable within a day — the same page range will always return the same companies for that day
Companies seen on a given day will not appear again on future days
Once all matching companies have been exhausted, no further results will be returned — create a new ICP with broader or different criteria to get fresh recommendations
If you receive empty results, your ICP filters may be too restrictive — consider relaxing them
Recommendations are charged at the end of the month based on the number of unique companies fetched. Fetching the same company multiple times counts as a single billable recommendation

Need Help?

If you have any questions or need further assistance, feel free to reach out to our support team via Intercom.

Additional Resources

API - Webhooks

API - What Are Recommendations?

API - Recommendations: Create or Update ICP

API - Recommendations: Get ICP Filters

API - Recommendations: Response Codes & Troubleshooting