Fetch recommendations

Fetch company and people recommendations that match your Ideal Customer Profile (ICP).

Before calling this endpoint, create an ICP using POST /v2/recommendations/icp and pass externalUserId.

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.

Empty results: An ICP with very restrictive filters may return no results if no companies match all the specified criteria. If you receive empty results, consider relaxing your ICP filters.

Use pagination.from and pagination.to to page through results. Each company in the response includes a list of matching people contacts and a recommendation object explaining why that account was recommended.

Billing: Recommendations are charged at the end of the month based on the number of unique companies fetched. Fetching the same company multiple times (e.g. across multiple API calls or pages) counts as a single billable recommendation.

Authorization

AuthorizationRequiredBearer <token>

In: header

Request Body

application/jsonRequired

Body

externalUserIdstring

ExternalUserID - Optional external user ID to filter recommendations. If not provided, recommendations associated with the authenticated user will be returned.

Maximum length: 255

paginationRequiredobject

curl -X POST "https://api.surfe.com/v2/recommendations/fetch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "ext-user-123",
    "pagination": {
      "from": 0,
      "to": 10
    }
  }'

{
  "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",
          "recommendation": {
            "generatedAt": "2024-05-20T10:00:00Z",
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "reasons": [
              {
                "data": {
                  "property1": null,
                  "property2": null
                },
                "description": "This company operates in your target industry",
                "score": 85,
                "shortDescription": "Industry match",
                "summary": {
                  "recommendationSummary": {
                    "statements": [
                      "Operates in your target industry",
                      "Has the right headcount"
                    ],
                    "subTitle": "This company is a strong match for your ICP",
                    "title": "Strong ICP match"
                  }
                },
                "title": "Matches your ICP",
                "type": "INDUSTRY_MATCH"
              }
            ]
          },
          "seniorities": [
            "Head"
          ],
          "summary": "Experienced sales leader with 10+ years"
        }
      ],
      "phones": [
        "+33 1 23 45 67 89"
      ],
      "recommendation": {
        "generatedAt": "2024-05-20T10:00:00Z",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reasons": [
          {
            "data": {
              "property1": null,
              "property2": null
            },
            "description": "This company operates in your target industry",
            "score": 85,
            "shortDescription": "Industry match",
            "summary": {
              "recommendationSummary": {
                "statements": [
                  "Operates in your target industry",
                  "Has the right headcount"
                ],
                "subTitle": "This company is a strong match for your ICP",
                "title": "Strong ICP match"
              }
            },
            "title": "Matches your ICP",
            "type": "INDUSTRY_MATCH"
          }
        ]
      },
      "size": "51-200",
      "yearFounded": 2020
    }
  ],
  "pagination": {
    "from": 0,
    "hasMore": true,
    "to": 10
  }
}

Fetch recommendations

Authorization

Request Body

Response

TypeScript