> For the complete documentation index, see [llms.txt](https://run.emailchaser.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run.emailchaser.com/api-reference/icps.md).

# ICPs

## List Ideal Customer Profiles

> Lists the caller's workspace ICPs, newest first.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ListICPsResponse":{"type":"object","properties":{"icps":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPResponse"}},"total":{"type":"integer"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps":{"get":{"description":"Lists the caller's workspace ICPs, newest first.","tags":["ICPs"],"summary":"List Ideal Customer Profiles","parameters":[{"schema":{"type":"integer"},"description":"Page size (default 50, max 200)","name":"limit","in":"query"},{"schema":{"type":"integer"},"description":"Page number, 1-based (default 1)","name":"page","in":"query"}],"responses":{"200":{"description":"Profiles and total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ListICPsResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"500":{"description":"Failed to retrieve profiles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Create an Ideal Customer Profile

> Stores a manually-authored ICP scoped to the caller's workspace. Set makePrimary to promote it to the workspace's active profile.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ICPResult":{"type":"object","properties":{"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.CreateICPRequest":{"type":"object","required":["name"],"properties":{"companySizes":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"makePrimary":{"description":"MakePrimary promotes this profile to the workspace's active one,\ndemoting any existing primary.","type":"boolean"},"name":{"type":"string"},"seniorities":{"type":"array","items":{"type":"string"}},"summary":{"description":"Summary is one to three sentences describing who the workspace sells to.","type":"string"},"titles":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/icps":{"post":{"description":"Stores a manually-authored ICP scoped to the caller's workspace. Set makePrimary to promote it to the workspace's active profile.","tags":["ICPs"],"summary":"Create an Ideal Customer Profile","responses":{"201":{"description":"The created profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ICPResult"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"500":{"description":"Failed to create the profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateICPRequest"}}},"description":"Profile fields","required":true}}}}}
```

## Get the primary Ideal Customer Profile

> Returns the workspace's active profile, or 404 when none is set.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ICPResult":{"type":"object","properties":{"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps/primary":{"get":{"description":"Returns the workspace's active profile, or 404 when none is set.","tags":["ICPs"],"summary":"Get the primary Ideal Customer Profile","responses":{"200":{"description":"The primary profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ICPResult"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"No primary profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to load the primary profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Get an Ideal Customer Profile

> Returns one profile. Profiles belonging to other workspaces are reported as not found.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ICPResult":{"type":"object","properties":{"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps/{id}":{"get":{"description":"Returns one profile. Profiles belonging to other workspaces are reported as not found.","tags":["ICPs"],"summary":"Get an Ideal Customer Profile","parameters":[{"schema":{"type":"integer"},"description":"Profile ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ICPResult"}}}},"400":{"description":"Invalid profile id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Profile not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Update an Ideal Customer Profile

> Applies a partial edit: omitted fields are unchanged, an empty list clears the list. Any edit marks the profile as human-authored.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ICPResult":{"type":"object","properties":{"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.UpdateICPRequest":{"type":"object","properties":{"companySizes":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"seniorities":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/icps/{id}":{"put":{"description":"Applies a partial edit: omitted fields are unchanged, an empty list clears the list. Any edit marks the profile as human-authored.","tags":["ICPs"],"summary":"Update an Ideal Customer Profile","parameters":[{"schema":{"type":"integer"},"description":"Profile ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"The updated profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ICPResult"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Profile not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateICPRequest"}}},"description":"Fields to change","required":true}}}}}
```

## Delete an Ideal Customer Profile

> Deletes a profile. Deleting the primary leaves the workspace without one.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.DeleteICPResponse":{"type":"object","properties":{"success":{"type":"boolean"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps/{id}":{"delete":{"description":"Deletes a profile. Deleting the primary leaves the workspace without one.","tags":["ICPs"],"summary":"Delete an Ideal Customer Profile","parameters":[{"schema":{"type":"integer"},"description":"Profile ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.DeleteICPResponse"}}}},"400":{"description":"Invalid profile id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Profile not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Refresh a profile's audience size

> Sizes the audience matching the profile's targeting criteria against the data provider and caches the result. Sizing is free.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.AudienceSizeResponse":{"type":"object","properties":{"audienceSize":{"type":"integer"},"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps/{id}/refresh-audience-size":{"post":{"description":"Sizes the audience matching the profile's targeting criteria against the data provider and caches the result. Sizing is free.","tags":["ICPs"],"summary":"Refresh a profile's audience size","parameters":[{"schema":{"type":"integer"},"description":"Profile ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"The refreshed profile and audience size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.AudienceSizeResponse"}}}},"400":{"description":"The profile has no targeting criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Profile not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"502":{"description":"Could not size the audience","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Set the primary Ideal Customer Profile

> Promotes a profile to the workspace's active one, demoting any existing primary.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.ICPResult":{"type":"object","properties":{"icp":{"$ref":"#/components/schemas/models.ICPResponse"}}},"models.ICPResponse":{"type":"object","properties":{"audienceSizedAt":{"description":"AudienceSizedAt is when the audience size was last refreshed (RFC3339),\nor null when it has never been sized.","type":"string"},"companySizes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"estimatedAudienceSize":{"type":"integer"},"id":{"type":"integer"},"industries":{"type":"array","items":{"type":"string"}},"isGenerated":{"description":"IsGenerated is true while the profile is exactly what the AI proposed;\nany human edit clears it.","type":"boolean"},"isPrimary":{"description":"IsPrimary marks the workspace's active profile. At most one per space.","type":"boolean"},"keywords":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/models.ICPPersona"}},"seniorities":{"type":"array","items":{"type":"string"}},"sourceWebsite":{"type":"string"},"summary":{"type":"string"},"titles":{"type":"array","items":{"type":"string"}}}},"models.ICPPersona":{"type":"object","properties":{"seniority":{"type":"string"},"title":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/icps/{id}/set-primary":{"post":{"description":"Promotes a profile to the workspace's active one, demoting any existing primary.","tags":["ICPs"],"summary":"Set the primary Ideal Customer Profile","parameters":[{"schema":{"type":"integer"},"description":"Profile ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"The promoted profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ICPResult"}}}},"400":{"description":"Invalid profile id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Profile not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```