Skip to content
CreatoRainCreatoRain API
Not live yet: the v1 API and its hosts are not open. See Sandbox.

Poll an onboarding session (session secret, no key)

GET
/onboarding_sessions/{id}
curl --request GET \
  --url https://api.creatorain.com/v1/onboarding_sessions/obs_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e \
  --header 'Authorization: Bearer <token>'

Authorization: Bearer <session_secret>. The first poll after the human approves carries key.secret; no later poll does (key_delivered: true, next_action: create_new_session if it was lost). Polling sooner than interval is 429 slow_down: the interval grows by 5 seconds, up to 60, and Retry-After carries it. A wrong secret and an unknown id are the same 404; failures count toward the address block like bad keys.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Example 

obs_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e

Responses

Section titled “Responses”

200

Section titled “200”

The session.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed values: onboarding_session
status
required
string
Allowed values: pending approved denied expired
expires_at
required
string format: date-time
interval
required
integer
key_delivered
required
boolean
key
required
object
id
required
string
secret

On the first poll after approval only.

string
prefix
required
string
last4
required
string
nullable
livemode
required
boolean
scopes
required
Array<string>
next_action
required

{type: human_approval, url} while pending; {type: create_new_session} once expired or collected.

object
type
string
Allowed values: human_approval create_new_session
url
string format: uri
blockers
required

Why the approval cannot produce a key yet (for example live_key_requires_top_up, key_limit_reached, owner_changed).

Array<string>

Example 

{
  "object": "onboarding_session",
  "status": "pending",
  "key": {
    "id": "key_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e",
    "prefix": "crp_test_AbCd"
  },
  "next_action": {
    "type": "human_approval"
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

Cache-Control
string
Allowed values: no-store

No-store. The answer may carry a secret.

401

Section titled “401”

Invalid_key, test_key_on_live or live_key_on_sandbox.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

404

Section titled “404”

Not_found.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

429

Section titled “429”

Rate_limited (600 a minute per workspace, an onboarding create limit, or an address blocked after failed authentication), or slow_down (an onboarding session polled too fast).

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

Retry-After
integer
>= 1

Seconds to wait before retrying (at least 1).

500

Section titled “500”

Internal_error (500) or service_unavailable (503). The message never carries a cause.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

503

Section titled “503”

Internal_error (500) or service_unavailable (503). The message never carries a cause.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.