Skip to content
TellMeHow Developers

API documentation

Engagements

Engagements: 55 API operations, with their parameters, body, responses and a curl example.

GET /client-companies

Read client-companies.index

Parameters

cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/client-companies" \
  -H "Authorization: Bearer pat_…"

POST /client-companies

Write client-companies.store

Body application/json

  • name string required

    length: at most 255

  • industry string | null

    length: at most 255

  • headcount integer | null

    at least 1 at most 10000000

  • country string | null

    length: exactly 2

  • notes string | null

    length: at most 5000

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/client-companies" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

PATCH /client-companies/{company}

Write client-companies.update

Parameters

company path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • industry string | null

    length: at most 255

  • headcount integer | null

    at least 1 at most 10000000

  • country string | null

    length: exactly 2

  • notes string | null

    length: at most 5000

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/client-companies/{company}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","industry":"…","headcount":1}'

DELETE /client-companies/{company}

Write client-companies.destroy

Parameters

company path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/client-companies/{company}" \
  -H "Authorization: Bearer pat_…"

GET /engagements

Read engagements.index

Parameters

cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements" \
  -H "Authorization: Bearer pat_…"

POST /engagements

Write engagements.store

Body application/json

  • name string required

    length: at most 255

  • client_company_id string required

    length: exactly 26

  • method_id string required

    length: exactly 26

  • method_version_id string | null

    length: exactly 26

  • locales array<string>

    items: at least 1

  • default_locale string | null

    length: at most 8

  • objectives string | null

    length: at most 10000

  • context string | null

    length: at most 20000

  • known_tools array<string>

    items: at most 60

  • vocabulary array<object>

    items: at most 100

  • vocabulary[].term string required

    length: at most 120

  • vocabulary[].meaning string | null

    length: at most 500

  • deadline_at string | null

    format date-time

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","client_company_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","method_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

GET /engagements/enums/blur-categories

Read engagements.enums.blur-categories

Parameters

cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/enums/blur-categories" \
  -H "Authorization: Bearer pat_…"

GET /engagements/enums/{name}

Read engagements.enums.show

Parameters

name path
Value from a fixed list (type, language, level…).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/enums/{name}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}

Read engagements.show

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}

Write engagements.update

Parameters

engagement path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • client_company_id string

    length: exactly 26

  • method_id string

    length: exactly 26

  • method_version_id string

    length: exactly 26

  • context string | null

    length: at most 20000

  • objectives string | null

    length: at most 10000

  • vocabulary array<object>

    items: at most 100

  • vocabulary[].term string required

    length: at most 120

  • vocabulary[].meaning string | null

    length: at most 500

  • known_tools array<string>

    items: at most 60

  • locales array<string>

    items: at least 1

  • default_locale string

    length: at most 8

  • sharing_mode object

    one of disabled anonymized by_role

  • naming_allowed boolean
  • deadline_at string | null

    format date-time

  • retention_raw_days integer

    at least 1 at most 3650

  • retention_deliverable_days integer

    at least 1 at most 3650

  • video_mode object

    one of full keyframes

  • tacit_validation_days integer | null

    at least 1 at most 60

  • blur_enabled boolean
  • blur_categories array<string>

    one of iban card nir email phone password custom mask

  • blur_custom_patterns array<object>

    items: at most 20

  • blur_custom_patterns[].label string required

    length: at most 120

  • blur_custom_patterns[].regex string required

    length: at most 500

  • posture_overrides array<object>
  • welcome_screen_overrides array<object>
  • reminder_schedule array<object>
  • reminder_schedule.enabled boolean
  • reminder_schedule.not_started_days array<integer>

    items: at most 6

  • reminder_schedule.unvalidated_days array<integer>

    items: at most 6

  • cse_informed_at string | null

    format date-time

  • cse_consulted_at string | null

    format date-time

  • budget_cap_session number | null

    at least 0 at most 100000

  • budget_cap_total number | null

    at least 0 at most 10000000

  • settings array<object>
  • settings.require_email_code boolean

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","client_company_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","method_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

DELETE /engagements/{engagement}

Write engagements.destroy

Parameters

engagement path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/archive

Write engagements.archive

Parameters

engagement path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/archive" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/blur-preview

Write engagements.blur-preview

Parameters

engagement path
Identifier (ULID).

Body application/json

  • text string required

    length: at most 5000

  • blur_categories array<string>
  • blur_custom_patterns array<object>

    items: at most 20

  • blur_custom_patterns[].label string required

    length: at most 120

  • blur_custom_patterns[].regex string required

    length: at most 500

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/blur-preview" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"…"}'

POST /engagements/{engagement}/invite-all

Write engagements.invite-all

Parameters

engagement path
Identifier (ULID).

Body application/json

  • only_not_invited boolean
  • participant_ids array<string>

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/invite-all" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"only_not_invited":true,"participant_ids":[]}'

POST /engagements/{engagement}/launch

Write engagements.launch

Parameters

engagement path
Identifier (ULID).

Body application/json

  • send_invitations boolean

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/launch" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"send_invitations":true}'

GET /engagements/{engagement}/launch-check

Read engagements.launch-check

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/launch-check" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/members

Write engagements.members.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • user_id string required

    length: exactly 26

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/members" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

DELETE /engagements/{engagement}/members/{user}

Write engagements.members.destroy

Parameters

engagement path
Identifier (ULID).
user path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/members/{user}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/message-templates

Read engagements.message-templates.index

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/message-templates" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/message-templates/{kind}/{locale}

Read engagements.message-templates.show

Parameters

engagement path
Identifier (ULID).
kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…"

PUT /engagements/{engagement}/message-templates/{kind}/{locale}

Write engagements.message-templates.update

Parameters

engagement path
Identifier (ULID).
kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).

Body application/json

  • subject string required

    length: at most 255

  • body_markdown string required

    length: at most 20000

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PUT "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"subject":"…","body_markdown":"…"}'

DELETE /engagements/{engagement}/message-templates/{kind}/{locale}

Write engagements.message-templates.destroy

Parameters

engagement path
Identifier (ULID).
kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/participants

Read engagements.participants.index

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/participants

Write engagements.participants.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • display_name string required

    length: at most 255

  • email string required

    length: at most 255 format email

  • role_title string required

    length: at most 255

  • population_id string required

    length: exactly 26

  • locale string | null

    length: at most 8

  • consultant_note string | null

    length: at most 5000

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"…","email":"name@example.com","role_title":"…","population_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

POST /engagements/{engagement}/participants/import

Write engagements.participants.import

Parameters

engagement path
Identifier (ULID).

Body multipart/form-data

  • file file required

    length: at most 1024

  • dry_run boolean
  • create_populations boolean

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/import" \
  -H "Authorization: Bearer pat_…" \
  -F "file=@./file.pdf"

GET /engagements/{engagement}/participants/{participant}

Read engagements.participants.show

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}/participants/{participant}

Write engagements.participants.update

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Body application/json

  • display_name string

    length: at most 255

  • email string

    length: at most 255 format email

  • role_title string

    length: at most 255

  • population_id string

    length: exactly 26

  • locale string | null

    length: at most 8

  • consultant_note string | null

    length: at most 5000

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"…","email":"name@example.com","role_title":"…"}'

DELETE /engagements/{engagement}/participants/{participant}

Write engagements.participants.destroy

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/participants/{participant}/invite

Write engagements.participants.invite

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Body application/json

  • locale string | null

    length: at most 8

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}/invite" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"locale":"…"}'

GET /engagements/{engagement}/participants/{participant}/messages

Read engagements.participants.messages

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}/messages" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/participants/{participant}/reinstate

Write engagements.participants.reinstate

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}/reinstate" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/participants/{participant}/remind

Write engagements.participants.remind

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}/remind" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/participants/{participant}/revoke

Write engagements.participants.revoke

Parameters

engagement path
Identifier (ULID).
participant path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/participants/{participant}/revoke" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/plan/{ownerType}/{ownerId}

Read engagements.plan.show

Parameters

engagement path
Identifier (ULID).
ownerType path
Value from a fixed list (type, language, level…).
ownerId path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/plan/{ownerType}/{ownerId}" \
  -H "Authorization: Bearer pat_…"

PUT /engagements/{engagement}/plan/{ownerType}/{ownerId}

Write engagements.plan.update

Parameters

engagement path
Identifier (ULID).
ownerType path
Value from a fixed list (type, language, level…).
ownerId path
Identifier (ULID).

Body application/json

  • chapters array<object>

    items: at most 30

  • chapters[].title string required

    length: at most 255

  • chapters[].topic_keys array<string>
  • chapters[].estimated_minutes integer | null

    at least 1 at most 240

  • chapters[].planned_session integer | null

    at least 1 at most 20

  • chapters[].origin object

    one of consultant ai_proposal ai_live analysis

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PUT "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/plan/{ownerType}/{ownerId}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"chapters":[]}'

GET /engagements/{engagement}/plan/{ownerType}/{ownerId}/proposals/{proposalId}

Read engagements.plan.proposals.show

Parameters

engagement path
Identifier (ULID).
ownerType path
Value from a fixed list (type, language, level…).
ownerId path
Identifier (ULID).
proposalId path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/plan/{ownerType}/{ownerId}/proposals/{proposalId}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/plan/{ownerType}/{ownerId}/propose

Write engagements.plan.propose

Parameters

engagement path
Identifier (ULID).
ownerType path
Value from a fixed list (type, language, level…).
ownerId path
Identifier (ULID).

Body application/json

  • locale string | null

    length: at most 8

  • target_minutes integer | null

    at least 10 at most 480

  • notes string | null

    length: at most 2000

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/plan/{ownerType}/{ownerId}/propose" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"locale":"…","target_minutes":10,"notes":"…"}'

GET /engagements/{engagement}/populations

Read engagements.populations.index

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/populations" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/populations

Write engagements.populations.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • description string | null

    length: at most 5000

  • expected_demonstrations array<string>

    items: at most 20

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/populations" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

POST /engagements/{engagement}/populations/reorder

Write engagements.populations.reorder

Parameters

engagement path
Identifier (ULID).

Body application/json

  • ids array<string> required

    items: at least 1

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/populations/reorder" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"ids":[]}'

PATCH /engagements/{engagement}/populations/{population}

Write engagements.populations.update

Parameters

engagement path
Identifier (ULID).
population path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • description string | null

    length: at most 5000

  • expected_demonstrations array<string>

    items: at most 20

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/populations/{population}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","description":"…","expected_demonstrations":[]}'

DELETE /engagements/{engagement}/populations/{population}

Write engagements.populations.destroy

Parameters

engagement path
Identifier (ULID).
population path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/populations/{population}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/progress

Read engagements.progress

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/progress" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/reopen

Write engagements.reopen

Parameters

engagement path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/reopen" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/sponsors

Read engagements.sponsors.index

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/sponsors" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/sponsors

Write engagements.sponsors.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • email string required

    length: at most 255 format email

  • name string | null

    length: at most 255

  • locale string | null

    length: at most 8

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/sponsors" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com"}'

DELETE /engagements/{engagement}/sponsors/{user}

Write engagements.sponsors.destroy

Parameters

engagement path
Identifier (ULID).
user path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/sponsors/{user}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/test-interview

Write engagements.test-interview

Parameters

engagement path
Identifier (ULID).

Body application/json

  • population_id string | null

    length: exactly 26

  • participant_id string | null

    length: exactly 26

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/test-interview" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"population_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","participant_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

GET /workspace/message-templates

Read workspace.message-templates.index

Parameters

cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/workspace/message-templates" \
  -H "Authorization: Bearer pat_…"

GET /workspace/message-templates/{kind}/{locale}

Read workspace.message-templates.show

Parameters

kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl "https://{your-workspace}.tellmehow.io/api/v1/workspace/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…"

PUT /workspace/message-templates/{kind}/{locale}

Write workspace.message-templates.update

Parameters

kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).

Body application/json

  • subject string required

    length: at most 255

  • body_markdown string required

    length: at most 20000

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X PUT "https://{your-workspace}.tellmehow.io/api/v1/workspace/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"subject":"…","body_markdown":"…"}'

DELETE /workspace/message-templates/{kind}/{locale}

Write workspace.message-templates.destroy

Parameters

kind path
Value from a fixed list (type, language, level…).
locale path
Value from a fixed list (type, language, level…).

Responses

  • 204 Deleted, no content.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example
curl -X DELETE "https://{your-workspace}.tellmehow.io/api/v1/workspace/message-templates/{kind}/{locale}" \
  -H "Authorization: Bearer pat_…"