Scoring

List scoring profiles

GET
/v1/scoring/profiles

List all scoring profiles for the authenticated organisation.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/scoring/profiles"
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "organizationId": "string",    "type": "company",    "name": "string",    "description": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }]

Create a scoring profile

POST
/v1/scoring/profiles

Create a named, org-scoped scoring profile. A profile groups scoring rules for a single object type (company or contact) and produces fit/urgency scores for any object assigned to it. A single object can be assigned to multiple profiles of the matching type.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

profileType*string

Object type this profile will score

Value in

  • "company"
  • "contact"
name*string
description?string|null

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/scoring/profiles" \  -H "Content-Type: application/json" \  -d '{    "profileType": "company",    "name": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "organizationId": "string",  "type": "company",  "name": "string",  "description": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Get a scoring profile

GET
/v1/scoring/profiles/{profileId}

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "organizationId": "string",  "type": "company",  "name": "string",  "description": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Delete a scoring profile

DELETE
/v1/scoring/profiles/{profileId}

Deletes the profile and cascades to its rules, assignments, and score results.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid

Response Body

application/json

curl -X DELETE "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty

Update a scoring profile

PUT
/v1/scoring/profiles/{profileId}

Rename or re-describe a profile. Profile type is immutable.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string
description?string|null

Response Body

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "organizationId": "string",  "type": "company",  "name": "string",  "description": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

List scoring rules for a profile

GET
/v1/scoring/profiles/{profileId}/rules

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08/rules"
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "signalTemplateId": "string",    "dimension": "fit",    "selector": "string",    "pointValues": {      "true": 0,      "false": 0,      "ranges": [        {          "min": 0,          "max": 0,          "points": 0        }      ],      "choices": {        "property1": 0,        "property2": 0      },      "mode": "additive"    },    "createdAt": "2019-08-24T14:15:22Z"  }]

Upsert a scoring rule

PUT
/v1/scoring/profiles/{profileId}/rules

Create or replace the rule for (profileId, signalTemplateId, dimension). Triggers a recompute of every object assigned to the profile so existing scores reflect the new rule immediately.

The shape of pointValues depends on the answer type of the referenced signal template:

  • boolean — { "true": 20, "false": -5 }
  • number / percentage / currency — { "ranges": [{ "min": 0, "max": 500, "points": 15 }] } (upper bound is exclusive)
  • list — { "choices": { "Salesforce": 10, "HubSpot": 8 }, "mode": "additive" } — mode is optional; supported values are additive (default), best-match, contains-all, contains-none, and exact-match.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

signalTemplateId*string
dimension*string

Value in

  • "fit"
  • "urgency"
answerType*string

Drives shape validation for pointValues. Must match the referenced signal template's answer type — mismatch surfaces as an INVALID_POINT_VALUES 422 at write time rather than a silent compute failure later.

Value in

  • "boolean"
  • "number"
  • "percentage"
  • "currency"
  • "list"
pointValues*

Point-value mapping for one rule. The shape varies by the answer type of the referenced signal template — exactly one of true/false, ranges, or choices is populated.

Response Body

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08/rules" \  -H "Content-Type: application/json" \  -d '{    "signalTemplateId": "string",    "dimension": "fit",    "answerType": "boolean",    "pointValues": {}  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",  "signalTemplateId": "string",  "dimension": "fit",  "selector": "string",  "pointValues": {    "true": 0,    "false": 0,    "ranges": [      {        "min": 0,        "max": 0,        "points": 0      }    ],    "choices": {      "property1": 0,      "property2": 0    },    "mode": "additive"  },  "createdAt": "2019-08-24T14:15:22Z"}

Delete a scoring rule

DELETE
/v1/scoring/profiles/{profileId}/rules/{ruleId}

Removes the rule and triggers a recompute of every object assigned to the profile so scores never silently go stale.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

profileId*string

Scoring profile UUID

Formatuuid
ruleId*string

Scoring rule UUID

Formatuuid

Response Body

application/json

curl -X DELETE "https://example.com/v1/scoring/profiles/497f6eca-6276-4993-bfeb-53cbbbba6f08/rules/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty

List profile assignments for an object

GET
/v1/scoring/assignments

Returns every profile a given object is assigned to.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Query Parameters

objectType*string

Object type (company or contact)

Value in

  • "company"
  • "contact"
objectId*string

For company use the domain (e.g. acme.com); for contact use the LinkedIn profile URL

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/scoring/assignments?objectType=company&objectId=string"
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "organizationId": "string",    "objectType": "company",    "objectId": "string",    "assignedAt": "2019-08-24T14:15:22Z"  }]

Assign a profile to a single object

POST
/v1/scoring/assignments

Links one company or contact to a scoring profile. Triggers immediate score computation so the score appears without waiting for the next signal run. Returns 422 if the object type does not match the profile's configured type.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

profileId*string
Formatuuid
objectType*string

Value in

  • "company"
  • "contact"
objectId*string

For company, the domain; for contact, the LinkedIn profile URL.

Length1 <= length <= 500

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/scoring/assignments" \  -H "Content-Type: application/json" \  -d '{    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "objectType": "company",    "objectId": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",  "organizationId": "string",  "objectType": "company",  "objectId": "string",  "assignedAt": "2019-08-24T14:15:22Z"}

Assign a profile to many objects at once

POST
/v1/scoring/assignments/bulk

Links many company or contact IDs to a single profile in one call. Skips duplicates (returns only newly created rows) and triggers an immediate score computation per newly assigned object.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

profileId*string
Formatuuid
objectType*string

Value in

  • "company"
  • "contact"
objectIds*array<>

Capped at 500 per request. Paginate larger lists by issuing multiple requests.

Items1 <= items <= 500

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/scoring/assignments/bulk" \  -H "Content-Type: application/json" \  -d '{    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "objectType": "company",    "objectIds": [      "string"    ]  }'
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "organizationId": "string",    "objectType": "company",    "objectId": "string",    "assignedAt": "2019-08-24T14:15:22Z"  }]

Remove a profile assignment

DELETE
/v1/scoring/assignments/{assignmentId}

Removes the assignment and cleans up any score results computed for this (profile, object) pair.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

assignmentId*string

Profile assignment UUID

Formatuuid

Response Body

application/json

curl -X DELETE "https://example.com/v1/scoring/assignments/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty

Read scores for one or more objects

GET
/v1/scoring/scores

Returns one row per (profile, object, dimension) triple. Pass objectId multiple times to read scores for several objects in a single call. The response includes the per-rule contribution breakdown so the score is always explainable.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Query Parameters

objectType*string

Value in

  • "company"
  • "contact"
objectId*array<string>

Repeatable. For company use the domain; for contact use the LinkedIn profile URL.

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/scoring/scores?objectType=company&objectId=string"
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "profileId": "faebe71b-2bf8-4bdb-9b67-258e4d6aa00a",    "organizationId": "string",    "objectType": "company",    "objectId": "string",    "dimension": "fit",    "score": 0,    "previousScore": 0,    "contributions": [      {        "ruleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",        "signalTemplateId": "string",        "matchedValue": "string",        "pointsEarned": 0,        "maxPoints": 0      }    ],    "previousContributions": [      {        "ruleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",        "signalTemplateId": "string",        "matchedValue": "string",        "pointsEarned": 0,        "maxPoints": 0      }    ],    "signalCoverage": 0,    "totalRules": 0,    "computedAt": "2019-08-24T14:15:22Z",    "version": 0  }]

Trigger score recomputation

POST
/v1/scoring/compute

Triggers score recomputation for the given objects against the latest signal data. Idempotent — duplicate triggers for the same object are deduplicated automatically.

Returns 202 Accepted with {queued, failed} counts as soon as dispatches finish (recomputation runs asynchronously; results become available via GET /v1/scoring/scores). A non-zero failed means some dispatches failed; if every dispatch fails the endpoint returns 502 instead.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

objectType*string

Value in

  • "company"
  • "contact"
objectIds*array<>

For company, domains; for contact, LinkedIn profile URLs. Capped at 500 per request — paginate larger lists.

Items1 <= items <= 500

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/scoring/compute" \  -H "Content-Type: application/json" \  -d '{    "objectType": "company",    "objectIds": [      "string"    ]  }'
{  "queued": 0,  "failed": 0}

On this page

List scoring profilesCreate a scoring profileGet a scoring profileDelete a scoring profileUpdate a scoring profileList scoring rules for a profileUpsert a scoring ruleDelete a scoring ruleList profile assignments for an objectAssign a profile to a single objectAssign a profile to many objects at onceRemove a profile assignmentRead scores for one or more objectsTrigger score recomputation