report | Botbye | Documentation

Tells BotBye how a challenge one of your users was given was answered — by your own MFA, by a captcha you run yourself, by ours solved out of band, or by a person in your support team.

A PASSED report may carry a grant, which makes the next requests of that user answer ALLOW where they would have answered CHALLENGE. A grant never lifts a BLOCK: a request we consider malicious is declined whatever a report said.

A FAILED report withdraws any grant standing on either identity it names, and may not carry one.

Endpoint

POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/reports

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project the challenge was issued for

Request Body

Field	Type	Required	Description
`subject`	object	Yes	Who the report is about
`subject.visitorId`	string	No	The BotBye visitor id the challenged request carried, up to 256 characters
`subject.userAccountId`	string	No	Your own account id for the end user, up to 256 characters
`subject.customFields`	object	No	Up to 5 of your own key/value pairs the granted requests must also carry
`result`	string	Yes	`PASSED` or `FAILED`
`channel`	string	Yes	What verified the person: `CAPTCHA`, `MFA`, `EXTERNAL_CAPTCHA` or `MANUAL`
`grant`	object	No	Present to buy a bypass; omit to file the report alone
`grant.ttlSeconds`	integer	Yes, within `grant`	How long the bypass lives, 60–86400
`grant.maxAttempts`	integer	No, within `grant`	How many requests it releases, at least 1; omit to release every request until the bypass expires

At least one of subject.visitorId and subject.userAccountId is required: a grant is keyed on one of them, and customFields can only narrow that key. A grant keyed on a custom field alone would be claimable by anyone who guessed the value, since custom fields arrive with every request.

subject.visitorId is only usable on requests that carry a BotBye token, which is where the visitor id can be verified. A report about a backend-only flow should name subject.userAccountId instead.

Response Structure

Field	Type	Description
`reportId`	string	Identifier of the report; also the id of the grant it issued
`grantExpiresAt`	string	Timestamp (epoch millis) the grant stops applying; absent when the report issued none
`grantRemainingAttempts`	integer	Requests the grant still releases; absent when the report issued none, and when the grant it issued counts no attempts

Use Cases

Support: a user cannot pass the captcha and contacts you; report the identity check your agent performed and let their next few requests through.
Your own MFA: report a passed multi-factor check so the user is not challenged again straight after it.
Third-party captcha: report the result of a captcha you run yourself.

Accepted permissions Project → Challenges → Action → Report challenge result

Token scope Project Action

# Report a Challenge Result Tells BotBye how a challenge one of your users was given was answered — by your own MFA, by a captcha you run yourself, by ours solved out of band, or by a person in your support team. A `PASSED` report may carry a **grant**, which makes the next requests of that user answer `ALLOW` where they would have answered `CHALLENGE`. A grant never lifts a `BLOCK`: a request we consider malicious is declined whatever a report said. A `FAILED` report withdraws any grant standing on either identity it names, and may not carry one. ## Endpoint ``` POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/reports ``` ## Authentication Requires API key authentication: ``` Authorization: Bearer {api_key} ``` ## Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | Yes | Your unique BotBye account identifier | | `project_id` | string | Yes | The project the challenge was issued for | ## Request Body | Field | Type | Required | Description | | --- | --- | --- | --- | | `subject` | object | Yes | Who the report is about | | `subject.visitorId` | string | No | The BotBye visitor id the challenged request carried, up to 256 characters | | `subject.userAccountId` | string | No | Your own account id for the end user, up to 256 characters | | `subject.customFields` | object | No | Up to 5 of your own key/value pairs the granted requests must also carry | | `result` | string | Yes | `PASSED` or `FAILED` | | `channel` | string | Yes | What verified the person: `CAPTCHA`, `MFA`, `EXTERNAL_CAPTCHA` or `MANUAL` | | `grant` | object | No | Present to buy a bypass; omit to file the report alone | | `grant.ttlSeconds` | integer | Yes, within `grant` | How long the bypass lives, 60–86400 | | `grant.maxAttempts` | integer | No, within `grant` | How many requests it releases, at least 1; omit to release every request until the bypass expires | At least one of `subject.visitorId` and `subject.userAccountId` is required: a grant is keyed on one of them, and `customFields` can only narrow that key. A grant keyed on a custom field alone would be claimable by anyone who guessed the value, since custom fields arrive with every request. `subject.visitorId` is only usable on requests that carry a BotBye token, which is where the visitor id can be verified. A report about a backend-only flow should name `subject.userAccountId` instead. ## Response Structure | Field | Type | Description | | --- | --- | --- | | `reportId` | string | Identifier of the report; also the id of the grant it issued | | `grantExpiresAt` | string | Timestamp (epoch millis) the grant stops applying; absent when the report issued none | | `grantRemainingAttempts` | integer | Requests the grant still releases; absent when the report issued none, and when the grant it issued counts no attempts | ## Use Cases - **Support**: a user cannot pass the captcha and contacts you; report the identity check your agent performed and let their next few requests through. - **Your own MFA**: report a passed multi-factor check so the user is not challenged again straight after it. - **Third-party captcha**: report the result of a captcha you run yourself. > **Accepted permissions** > `Project → Challenges → Action → Report challenge result` > > **Token scope** > `Project Action`

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Personal access token. Create it in your BotBye account under **Profile → Personal Access Tokens**, tick the scopes the endpoints you call require (see each endpoint's **Token scope**), and send the token in the `X-Api-Key` request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired

project_idstringRequired

Request

This endpoint expects an object.

subjectobjectRequired

resultenumRequired

Allowed values:

channelenumRequired

Allowed values:

grantobjectOptional

Response

success

reportIdstringformat: "uuid"

grantExpiresAtstringOptional

grantRemainingAttemptsintegerOptional

Errors

400

Bad Request Error

Tells BotBye how a challenge one of your users was given was answered — by your own MFA, by a captcha you run yourself, by ours solved out of band, or by a person in your support team.

A FAILED report withdraws any grant standing on either identity it names, and may not carry one.

Endpoint

POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/reports

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project the challenge was issued for

Request Body

Field	Type	Required	Description
`subject`	object	Yes	Who the report is about
`subject.visitorId`	string	No	The BotBye visitor id the challenged request carried, up to 256 characters
`subject.userAccountId`	string	No	Your own account id for the end user, up to 256 characters
`subject.customFields`	object	No	Up to 5 of your own key/value pairs the granted requests must also carry
`result`	string	Yes	`PASSED` or `FAILED`
`channel`	string	Yes	What verified the person: `CAPTCHA`, `MFA`, `EXTERNAL_CAPTCHA` or `MANUAL`
`grant`	object	No	Present to buy a bypass; omit to file the report alone
`grant.ttlSeconds`	integer	Yes, within `grant`	How long the bypass lives, 60–86400
`grant.maxAttempts`	integer	No, within `grant`	How many requests it releases, at least 1; omit to release every request until the bypass expires

Response Structure

Field	Type	Description
`reportId`	string	Identifier of the report; also the id of the grant it issued
`grantExpiresAt`	string	Timestamp (epoch millis) the grant stops applying; absent when the report issued none
`grantRemainingAttempts`	integer	Requests the grant still releases; absent when the report issued none, and when the grant it issued counts no attempts

Use Cases

Support: a user cannot pass the captcha and contacts you; report the identity check your agent performed and let their next few requests through.
Your own MFA: report a passed multi-factor check so the user is not challenged again straight after it.
Third-party captcha: report the result of a captcha you run yourself.

Accepted permissions Project → Challenges → Action → Report challenge result

Token scope Project Action