REST reference · v1

Queue an identity verification

POST/v1/workspaces/{workspaceId}/connections/{connectionId}/verify

Provider verify permission, implemented identity adapter and current entitlement/quota. Requires Idempotency-Key; replay with the same workspace/requester/key and connection returns the existing job, possibly already terminal. A different connection conflicts.

Company permissions

Required OAuth scopes: orchesphere.read, orchesphere.jobs. How scopes and company rights work.

Path and header parameters

Name	Location	Required	Allowed values / bounds
`workspaceId`	path	Yes	`string` minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$
`connectionId`	path	Yes	`string` minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$
`Idempotency-Key`	header	Yes	`string` minLength: 8 · maxLength: 100 · pattern: ^[A-Za-z0-9_-]{8,100}$ Unique workspace/requester key; reuse only for this same connection submission.

Request

JSON body: optional; omit it or use the documented empty object.

No input fields are required.

Complete request schema

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

http

POST /v1/workspaces/{workspaceId}/connections/{connectionId}/verify HTTP/1.1
Host: api.orchesphere.ai
Authorization: Bearer <access_token>
Accept: application/json
Idempotency-Key: example-verify-001
Content-Type: application/json

{}

Use actual IDs returned for your assigned workspace. The example values are fictional. REST v1 accepts no query parameters.

Response · 202

Field	Type	Required	Description / bounds
`job`	`object`	Yes	—

Complete response schema

{
  "type": "object",
  "properties": {
    "job": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "connectionId": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "provider": {
          "type": "string"
        },
        "environment": {
          "type": "string",
          "enum": [
            "production",
            "sandbox"
          ]
        },
        "operation": {
          "type": "string",
          "const": "verify"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "running",
            "retry_wait",
            "succeeded",
            "failed",
            "blocked",
            "cancelled"
          ]
        },
        "attempts": {
          "type": "integer",
          "minimum": 0
        },
        "createdBy": {
          "type": "string"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "finishedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "result": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "accountId": {
                  "type": "string"
                },
                "companyName": {
                  "type": "string"
                },
                "observedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "identityLabelKind": {
                  "type": "string",
                  "enum": [
                    "account_label",
                    "company_name"
                  ]
                },
                "credentialRenewedAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "accountId",
                "companyName",
                "observedAt",
                "identityLabelKind",
                "credentialRenewedAt"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "errorCode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "canCancel": {
          "type": "boolean"
        },
        "canResume": {
          "type": "boolean"
        },
        "resumeBlockedReason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "connectionId",
        "provider",
        "operation",
        "status",
        "attempts",
        "createdBy",
        "createdAt",
        "updatedAt",
        "finishedAt",
        "result",
        "errorCode",
        "error"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "job"
  ],
  "additionalProperties": false
}

json

{
  "job": {
    "id": "33333333-3333-4333-8333-333333333333",
    "connectionId": "22222222-2222-4222-8222-222222222222",
    "provider": "quickbooks",
    "operation": "verify",
    "status": "queued",
    "attempts": 0,
    "createdBy": "developer@example.com",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "finishedAt": null,
    "result": null,
    "errorCode": null,
    "error": null
  }
}

Errors

Status	Meaning
`400`	Invalid path/query/body/header or business validation.
`401`	Missing, expired, revoked, invalid or wrong-resource token.
`402`	Verified company payment is required.
`403`	Insufficient token scope or current company/service/portal/task authority.
`404`	Unknown endpoint or record not found/inaccessible.
`405`	Method is not supported for this path.
`409`	State, quota or idempotency conflict; re-read current state.
`413`	Request exceeds 24,000 bytes.
`415`	Use uncompressed application/json.
`429`	Company job/rate/paid-period allowance reached.
`503`	Temporarily unavailable; a lost mutation response does not prove nothing was saved.

Request limits and recovery · All REST operations