Customer profiles

This page shows how to make and keep a customer profile, which is what scoring and scouts read to decide who fits.

A customer profile says who a workspace sells to: the titles, industries and places you aim for, what you avoid, and why a buyer picks you. Make one first. Everything else that checks fit points at it.

What a profile holdsCopy Anchor Link

The profile object holds short phrases, grouped like this:

Is it ready?Copy Anchor Link

A profile needs at least one target title, industry or keyword, one value proposition and one pain point before it can score people. Every answer has a ready object:

"ready": {
  "for_scoring": false,
  "for_scouts": false,
  "missing": [
    "Add at least one target title, industry or keyword.",
    "Add at least one value proposition.",
    "Add at least one pain point."
  ]
}

Check ready.for_scoring and ready.for_scouts before you score or start a scout. If you do not, the call is refused with 422 profile_not_ready and fix says what to add.

The main callsCopy Anchor Link

Make a profileCopy Anchor Link

POST /customer_profiles makes a profile in one of three ways. Send exactly one shape.

From a website. done. reads the site and builds the profile. It answers 202 at once with research.status of researching.

curl https://api.done.com/v1/customer_profiles \
  -H "Authorization: Bearer $DONE_API_KEY" \
  -H "Idempotency-Key: 4d8e1f20-7a63-4b9c-a1e2-90c5d3f7b681" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "lumenpay.example",
    "name": "Lumen Invoicing for finance teams"
  }'

By hand. Save a profile you wrote. Saving it is free and answers 201. When the profile has a product description, done. then prepares scoring examples from it in the background, which costs about 0.35. That charge happens after the answer, counts against the key's daily credit cap, and is skipped (nothing charged) when the cap or the credits would not cover it. The name, description, website and profile together may be at most 60,000 bytes written as JSON.

curl https://api.done.com/v1/customer_profiles \
  -H "Authorization: Bearer $DONE_API_KEY" \
  -H "Idempotency-Key: 9b3c7e14-52d0-4a8f-86c1-e47a02d9f35b" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lumen Invoicing for finance teams",
    "description": "Invoicing and collections for finance teams at UK fintechs.",
    "profile": {
      "aim_for": {
        "titles": ["CFO", "Finance Director"],
        "industries": ["Fintech"],
        "keywords": ["cash flow"]
      },
      "value_propositions": ["Cuts invoice chasing time by half"],
      "pain_points": ["Late payments strain cash flow"],
      "places": ["United Kingdom"]
    }
  }'

From pasted text. Send name and document_text, up to 17,000 characters. It answers 202 and costs about 6.1. The first research in an organization is free, here too.

By hand only: if a profile with the same name already exists, and its website is the same or either has none, nothing is created and nothing is charged. The call answers 200 with that profile.

Wait for researchCopy Anchor Link

Research from a website or from text runs in the background. Poll GET /customer_profiles/{id} every 10 to 30 seconds until research.status is done, failed or cancelled.

curl https://api.done.com/v1/customer_profiles/cp_6TnR4cVd \
  -H "Authorization: Bearer $DONE_API_KEY"

Change a profileCopy Anchor Link

PATCH /customer_profiles/{id} changes the name, description, website or any part of the profile. Send only what you want to change. A list you send replaces that whole list, so to add one title, send all the titles.

curl -X PATCH https://api.done.com/v1/customer_profiles/cp_6TnR4cVd \
  -H "Authorization: Bearer $DONE_API_KEY" \
  -H "Idempotency-Key: 2f6a9c31-0b47-4d5e-9a18-c3e7b5d40f92" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": { "aim_for": { "titles": ["CFO", "Finance Director", "Head of Finance", "VP Finance"] } }
  }'

The change applies from the next person scored. People already scored are not scored again. While research is running, a change is refused with research_in_progress, because the research would overwrite it. The name, description, website and profile after any change may be at most 60,000 bytes written as JSON. A change that would pass that and make the profile larger is refused with invalid_field, naming profile or the field that grew it. A change that does not make a larger profile grow, such as a shorter name, still applies.

The change itself is free. When the profile part changes and the profile has a product description, done. prepares new scoring examples in the background, which costs about 0.35. That charge happens after the answer, once per version of the profile, counts against the key's daily credit cap, and is skipped when the cap or the credits would not cover it.

Research again, cancel, deleteCopy Anchor Link

• POST /customer_profiles/{id}/research researches the profile's website again and builds the profile from what is found. While it runs, the profile is empty. The profile needs a website. If research is already running, the call is refused with research_in_progress.
• POST /customer_profiles/{id}/research/cancel stops research that is running. If none is running, it is refused with not_running.
• DELETE /customer_profiles/{id} deletes a profile for good. It is refused with profile_in_use while any scoring run is using it.
• GET /customer_profiles lists profiles, newest first.

What it costsCopy Anchor Link

Credits are held when research starts. If research is cancelled before paid work has started, they come back. If credits run out, add credits or use the by-hand shape: saving it is free, and the scoring examples it may prepare (about 0.35, when the profile has a product description) are skipped when the credits would not cover them. See Credits and costs.

Rules that applyCopy Anchor Link

• Making, changing and researching again need the spend permission. Deleting one needs full. Reading needs read.
• Making, changing and researching again need an Idempotency-Key. See Safe retries.
• A profile that is being researched cannot start a scoring run. The run is refused with research_in_progress.
• Test keys charge no credits and return sample answers for paid work.