> For the complete documentation index, see [llms.txt](https://detected.gitbook.io/detected-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://detected.gitbook.io/detected-api-docs/api-reference/representatives/verification-flow.md).

# Verification Flow

The verification flow is the journey a representative completes in the verify portal. Retrieve or update the configuration that applies to a representative, create a login link for them to start verifying, or reset the flow and send them a fresh link.

## Retrieve a representative verification configuration

> Returns the verification flow configuration that applies to the representative. The configuration is resolved by precedence: a configuration assigned to the representative, then the configuration linked to their verification flow, then global verification configurations matching the profile country and the representative's types.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representative Verification Flow","description":"The verification flow is the journey a representative completes in the verify portal. Retrieve or update the configuration that applies to a representative, create a login link for them to start verifying, or reset the flow and send them a fresh link."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"schemas":{"PersonVerifyDataConfigurationResource":{"title":"Verify Configuration","required":["people_types","id3","id_document","forms","personal_information"],"properties":{"people_types":{"description":"The people types of the representative.","type":"array","items":{"properties":{"id":{"type":"integer"},"label":{"type":"string"},"type":{"type":"string"}},"type":"object"}},"id3":{"description":"ID3 identity check step.","properties":{"enabled":{"type":"boolean"}},"type":"object"},"id_document":{"description":"ID verification (document) step.","properties":{"enabled":{"type":"boolean"},"options":{"properties":{"fallback":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"liveness":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"facematch":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"document_upload":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}},"type":"object"}},"type":"object"},"forms":{"description":"Forms step. `enabled` is true when the resolved configuration has forms assigned.","properties":{"enabled":{"type":"boolean"},"data":{"description":"Forms assigned to the representative.","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"reference":{"type":"string"}},"type":"object"}}},"type":"object"},"personal_information":{"description":"Personal information (edit details) step.","properties":{"enabled":{"type":"boolean"},"data":{"description":"People models defining the editable fields per people type.","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"description":"People type the model applies to.","type":"string"}},"type":"object"}}},"type":"object"}},"type":"object"}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}/verify-configuration":{"get":{"tags":["Representative Verification Flow"],"summary":"Retrieve a representative verification configuration","description":"Returns the verification flow configuration that applies to the representative. The configuration is resolved by precedence: a configuration assigned to the representative, then the configuration linked to their verification flow, then global verification configurations matching the profile country and the representative's types.","operationId":"0223c669b7f28a2d0ea4f4f4638bca54","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PersonVerifyDataConfigurationResource"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Update a representative verification configuration

> Creates or updates the verification flow configuration assigned to the representative. Omitted fields keep the values of the currently resolved configuration. If the representative does not have a verification flow yet, one is created.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representative Verification Flow","description":"The verification flow is the journey a representative completes in the verify portal. Retrieve or update the configuration that applies to a representative, create a login link for them to start verifying, or reset the flow and send them a fresh link."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"schemas":{"VerifyConfigurationUpsertRequest":{"title":"Verify Configuration Update Request","description":"Changes to the verification flow configuration of a representative. All fields are optional; omitted fields keep the values of the currently resolved configuration.","properties":{"forms":{"description":"Forms step configuration.","properties":{"enable":{"description":"Whether the representative is asked to complete forms.","type":"boolean"},"ids":{"description":"Ids of the forms assigned to the representative.","type":"array","items":{"type":"integer"}}},"type":"object"},"id3":{"description":"ID3 identity check step configuration.","properties":{"enable":{"description":"Whether the ID3 identity check is performed.","type":"boolean"}},"type":"object"},"personal_information":{"description":"Personal information (edit details) step configuration. `enable` is required when this object is sent.","required":["enable"],"properties":{"enable":{"description":"Whether the representative is asked to review and edit their personal information.","type":"boolean"}},"type":"object"},"id_document":{"description":"ID verification (document) step configuration.","properties":{"enable":{"description":"Whether the representative is asked to verify an identity document.","type":"boolean"}},"type":"object"}},"type":"object"},"PersonVerifyConfigurationVersionResource":{"title":"Verify Configuration Version","required":["id3","id_document","forms","personal_information"],"properties":{"people_types":{"description":"People types the configuration applies to. Only returned when the configuration type includes people types.","properties":{"enabled":{"type":"boolean"},"data":{"type":"array","items":{"properties":{"id":{"type":"integer"},"label":{"type":"string"},"type":{"type":"string"}},"type":"object"}}},"type":"object"},"id3":{"description":"ID3 identity check step.","properties":{"enabled":{"type":"boolean"}},"type":"object"},"id_document":{"description":"ID verification (document) step.","properties":{"enabled":{"type":"boolean"},"options":{"properties":{"fallback":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"liveness":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"facematch":{"properties":{"enabled":{"type":"boolean"}},"type":"object"},"document_upload":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}},"type":"object"}},"type":"object"},"forms":{"description":"Forms step. `enabled` is true when the configuration version has forms assigned.","properties":{"enabled":{"type":"boolean"},"data":{"description":"Forms assigned to the representative.","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"reference":{"type":"string"}},"type":"object"}}},"type":"object"},"personal_information":{"description":"Personal information (edit details) step.","properties":{"enabled":{"type":"boolean"},"data":{"description":"People models defining the editable fields per people type.","type":"array","items":{"properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"description":"People type the model applies to.","type":"string"}},"type":"object"}}},"type":"object"}},"type":"object"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"400":{"description":"Bad Request. The request could not be processed because it is invalid. The `message` field explains why.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"422":{"description":"Unprocessable Content. The request was understood but failed validation. `errors` lists each field that failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"description":"A human-readable description of the first error.","type":"string"},"errors":{"description":"Validation errors, keyed by the name of the field that failed. Each field has a list of messages.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}/verify-configuration":{"patch":{"tags":["Representative Verification Flow"],"summary":"Update a representative verification configuration","description":"Creates or updates the verification flow configuration assigned to the representative. Omitted fields keep the values of the currently resolved configuration. If the representative does not have a verification flow yet, one is created.","operationId":"f4ca86efd263928ee7da657b0461c429","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyConfigurationUpsertRequest"}}}},"responses":{"200":{"description":"OK, the latest configuration version was updated in place","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PersonVerifyConfigurationVersionResource"}},"type":"object"}}}},"201":{"description":"Created, a new configuration version was created","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PersonVerifyConfigurationVersionResource"}},"type":"object"}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Create a representative login link

> Creates a login link for a representative. The representative uses the link to sign in and complete the action given in \`purpose\`. Currently the only supported purpose is \`verify\`.\
> \
> The response includes the time at which the link expires (\`expires\_at\`). If the link has expired, the verify portal takes the representative through a one-time passcode (OTP) flow to sign in, so no further API calls are needed.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representative Verification Flow","description":"The verification flow is the journey a representative completes in the verify portal. Retrieve or update the configuration that applies to a representative, create a login link for them to start verifying, or reset the flow and send them a fresh link."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"schemas":{"PersonLoginLinkCreateRequest":{"title":"Representative Login Link Create Request","required":["purpose"],"properties":{"purpose":{"description":"Purpose of the login link. Currently only `verify` is supported.","type":"string","enum":["verify"],"nullable":false}},"type":"object"},"PersonLinkLoginResourceResponse":{"title":"Representative Login Link Resource","required":["purpose","link","expires_at"],"properties":{"purpose":{"description":"Purpose the login link was created for.","type":"string","enum":["verify"],"nullable":false},"link":{"description":"URL the representative uses to sign in.","type":"string","nullable":false},"expires_at":{"description":"Date and time at which the link expires.","type":"string","nullable":false}},"type":"object"}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}/login-links":{"post":{"tags":["Representative Verification Flow"],"summary":"Create a representative login link","description":"Creates a login link for a representative. The representative uses the link to sign in and complete the action given in `purpose`. Currently the only supported purpose is `verify`.\n\nThe response includes the time at which the link expires (`expires_at`). If the link has expired, the verify portal takes the representative through a one-time passcode (OTP) flow to sign in, so no further API calls are needed.","operationId":"73265b841557f696291ea42f7fad3b67","parameters":[{"$ref":"#/components/parameters/representativeUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonLoginLinkCreateRequest"}}}},"responses":{"201":{"description":"Created","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PersonLinkLoginResourceResponse"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```

## Reset the verification flow for a representative

> Resets the verification flow for a representative and sends them a fresh verification link by email. Send \`notify=0\` to reset the flow without sending the email. This is the same as the "Reset verification" action in case management. If the representative has no active verification flow, nothing happens and no email is sent.

```json
{"openapi":"3.0.0","info":{"title":"Detected API","version":"v2"},"tags":[{"name":"Representative Verification Flow","description":"The verification flow is the journey a representative completes in the verify portal. Retrieve or update the configuration that applies to a representative, create a login link for them to start verifying, or reset the flow and send them a fresh link."}],"servers":[{"url":"https://api.detected.app/api/v2/public","description":"Production"}],"security":[{"AccessToken":[]}],"components":{"securitySchemes":{"AccessToken":{"type":"http","description":"The API uses OAuth 2.0. Request an access token with **Create an access token** (`POST /oauth/token`), sending the client ID and client secret of your integration client, and your account slug. Send the access token in the `Authorization` header of every request, in the format `Authorization: Bearer <access_token>`. The access token carries the scopes set on your integration client in the dashboard. Access tokens expire. When one expires, request a new one.","bearerFormat":"OAuth 2.0 access token","scheme":"bearer"}},"parameters":{"representativeUuid":{"name":"uuid","in":"path","description":"UUID of the representative.","required":true,"schema":{"type":"string","format":"uuid","nullable":false}}},"headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the rate limit window.","schema":{"type":"number","nullable":false}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current rate limit window.","schema":{"type":"number","nullable":false}},"Retry-After":{"description":"Number of seconds to wait before making another request. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}},"X-RateLimit-Reset":{"description":"Unix timestamp (in seconds) at which the rate limit resets. Returned when the rate limit has been reached.","schema":{"type":"number","nullable":false}}},"responses":{"401":{"description":"Unauthorized. The access token is missing, invalid or has expired.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}},"404":{"description":"Not Found. The requested resource does not exist, or is not available to your account.","content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"},"error":{"description":"Machine-readable details of the error.","type":"object","properties":{"key":{"description":"Error code, for example `error.generic`.","type":"string"},"params":{"description":"Values used in the error message, if any.","type":"array","items":{}}}}},"type":"object"}}}},"429":{"description":"Too Many Requests. You have exceeded the rate limit. Wait for the number of seconds given in the `Retry-After` header before trying again.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"properties":{"message":{"description":"A human-readable description of the error.","type":"string"}},"type":"object"}}}}}},"paths":{"/representatives/{uuid}/verify-flow":{"delete":{"tags":["Representative Verification Flow"],"summary":"Reset the verification flow for a representative","description":"Resets the verification flow for a representative and sends them a fresh verification link by email. Send `notify=0` to reset the flow without sending the email. This is the same as the \"Reset verification\" action in case management. If the representative has no active verification flow, nothing happens and no email is sent.","operationId":"4c1c39257528488b71bc5e87cbe8f92f","parameters":[{"$ref":"#/components/parameters/representativeUuid"},{"name":"notify","in":"query","description":"Whether to email the representative a new verification link when the flow is reset. Send `1` to send the email, or `0` to reset the flow without sending it. The default is `1`.","schema":{"type":"integer","enum":[0,1]}}],"responses":{"204":{"description":"No Content. The verification flow was reset and the representative was emailed a new link, or there was no active flow and nothing was done.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}}},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://detected.gitbook.io/detected-api-docs/api-reference/representatives/verification-flow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.