API - Recommendations: Create or Update ICP – SURFE

Use this endpoint to create or update your Ideal Customer Profile (ICP). Your ICP defines the characteristics of the companies and people you want to target when fetching recommendations.

Each externalUserId can have one ICP — calling this endpoint again for the same externalUserId replaces the existing one. If externalUserId is omitted, the ICP is associated with the authenticated user.

For details on available filter values, use the Get Filters endpoint.

Endpoint

POST /v2/recommendations/icp

Headers

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

Request Body

{
  "companies": {
    "employeeCount": {
      "from": 1,
      "to": 100000000
    },
    "industries": [
      "Software",
      "Finance"
    ],
    "primaryLocations": [
      "fr",
      "W-EMEA"
    ],
    "revenue": {
      "from": 1,
      "to": 100000000
    }
  },
  "externalUserId": "ext-user-123",
  "people": {
    "countries": [
      "fr",
      "W-EMEA"
    ],
    "departments": [
      "Engineering",
      "Marketing"
    ],
    "jobTitles": [
      "Software Engineer",
      "Marketing Manager"
    ],
    "seniorities": [
      "C-Level",
      "Director",
      "Founder"
    ]
  }
}

Fields Explained

companies object:

employeeCount — filter by company size. Set from and to values
industries — list of target industries. Use Get Filters endpoint for accepted values
primaryLocations — accepts ISO 3166 alpha-2 country codes (e.g. "fr") or world region codes (e.g. "W-EMEA")
revenue — filter by revenue range. Set from and to values

people object:

countries — accepts ISO 3166 alpha-2 country codes or world region codes
departments — list of target departments. Use Get Filters endpoint for accepted values
jobTitles — list of target job titles
seniorities — list of target seniority levels. Use Get Filters endpoint for accepted values

ExternalUserId — optional string (maximum 250 characters). Your own internal identifier to associate this ICP with a specific user in your system. If not provided, the ICP is associated with the authenticated user.

Important

The more filters you set, the fewer recommendations you will receive. If you're getting no results when fetching recommendations, try relaxing your ICP filters.

Example Response

{
  "companies": {
    "employeeCount": {
      "from": 1,
      "to": 100000000
    },
    "industries": [
      "Software",
      "Finance"
    ],
    "primaryLocations": [
      "fr",
      "W-EMEA"
    ],
    "revenue": {
      "from": 1,
      "to": 100000000
    }
  },
  "externalUserId": "ext-user-123",
  "id": "00000000-0000-0000-0000-000000000000",
  "people": {
    "countries": [
      "fr",
      "W-EMEA"
    ],
    "departments": [
      "Engineering",
      "Marketing"
    ],
    "jobTitles": [
      "Software Engineer",
      "Marketing Manager"
    ],
    "seniorities": [
      "C-Level",
      "Director",
      "Founder"
    ]
  }
}

The response returns your saved ICP along with a unique id. Use the externalUserId when calling the Fetch Recommendations endpoint to receive matching results.

Need Help?

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

Additional Resources