> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/accounts-api/api-reference/organizations/approvals.md).

# Approvals

## GET /organizations/{organizationId}/approvals

> List approval flows

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage which actions require an approval process.","name":"organization_approvals"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}},"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}},"approvalFlowStatus":{"in":"query","name":"status","required":false,"schema":{"default":"active","enum":["active","deleted"],"type":"string"}},"approvalFlowObjectType":{"in":"query","name":"objectType","required":false,"schema":{"$ref":"#/components/schemas/objectType"}},"approvalFlowObjectAction":{"in":"query","name":"objectAction","required":false,"schema":{"$ref":"#/components/schemas/objectAction"}},"approvalFlowTags":{"in":"query","name":"tags","required":false,"schema":{"type":"string"}}},"schemas":{"objectType":{"type":"string","format":"mrn","description":"The identifier of the object"},"objectAction":{"type":"string","enum":["create","update","delete"],"description":"The action performed on the object"},"ApprovalFlowList":{"type":"object","title":"ApprovalFlowList","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalFlow"}}},"required":["results"]},"ApprovalFlow":{"type":"object","title":"ApprovalFlow","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"objectType":{"$ref":"#/components/schemas/objectType"},"objectAction":{"$ref":"#/components/schemas/objectAction"},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type","users"]},"minItems":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/approvalFlowIdentifierTag"}}},"required":["id","ownerId","name","description","objectType","objectAction","steps","createdAt","updatedAt"]},"approvalStepReviewer":{"type":"object","title":"ApprovalStepReviewer","description":"Reference to an entity that can review the runs for this flow.","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"approvalFlowIdentifierTag":{"type":"object","title":"ApprovalFlowIdentifierTag","description":"A tag that can be used to identify this flow.","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/approvals":{"get":{"operationId":"listOrganizationApprovalFlows","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/direction"},{"$ref":"#/components/parameters/approvalFlowStatus"},{"$ref":"#/components/parameters/approvalFlowObjectType"},{"$ref":"#/components/parameters/approvalFlowObjectAction"},{"$ref":"#/components/parameters/approvalFlowTags"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApprovalFlowList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"List approval flows","tags":["organization_approvals"]}}}}
```

## POST /organizations/{organizationId}/approvals

> Create approval flow

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage which actions require an approval process.","name":"organization_approvals"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateApprovalFlow":{"type":"object","title":"CreateApprovalFlow","additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"type":"string"},"objectType":{"$ref":"#/components/schemas/objectType"},"objectAction":{"$ref":"#/components/schemas/objectAction"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/approvalFlowIdentifierTag"}},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type"]},"minItems":1}},"required":["name","description","objectType","objectAction","steps"]},"objectType":{"type":"string","format":"mrn","description":"The identifier of the object"},"objectAction":{"type":"string","enum":["create","update","delete"],"description":"The action performed on the object"},"approvalFlowIdentifierTag":{"type":"object","title":"ApprovalFlowIdentifierTag","description":"A tag that can be used to identify this flow.","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"approvalStepReviewer":{"type":"object","title":"ApprovalStepReviewer","description":"Reference to an entity that can review the runs for this flow.","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"ApprovalFlow":{"type":"object","title":"ApprovalFlow","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"objectType":{"$ref":"#/components/schemas/objectType"},"objectAction":{"$ref":"#/components/schemas/objectAction"},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type","users"]},"minItems":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/approvalFlowIdentifierTag"}}},"required":["id","ownerId","name","description","objectType","objectAction","steps","createdAt","updatedAt"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource."},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/approvals":{"post":{"operationId":"createOrganizationApprovalFlow","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApprovalFlow"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalFlow"}}},"description":"OK"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create approval flow","tags":["organization_approvals"]}}}}
```

## GET /organizations/{organizationId}/approvals/{approvalId}

> Retrieve approval flow

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage which actions require an approval process.","name":"organization_approvals"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"ApprovalFlow":{"type":"object","title":"ApprovalFlow","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"objectType":{"$ref":"#/components/schemas/objectType"},"objectAction":{"$ref":"#/components/schemas/objectAction"},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type","users"]},"minItems":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/approvalFlowIdentifierTag"}}},"required":["id","ownerId","name","description","objectType","objectAction","steps","createdAt","updatedAt"]},"objectType":{"type":"string","format":"mrn","description":"The identifier of the object"},"objectAction":{"type":"string","enum":["create","update","delete"],"description":"The action performed on the object"},"approvalStepReviewer":{"type":"object","title":"ApprovalStepReviewer","description":"Reference to an entity that can review the runs for this flow.","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"approvalFlowIdentifierTag":{"type":"object","title":"ApprovalFlowIdentifierTag","description":"A tag that can be used to identify this flow.","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/approvals/{approvalId}":{"get":{"operationId":"getOrganizationApprovalFlow","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalFlow"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Retrieve approval flow","tags":["organization_approvals"]}}}}
```

## DELETE /organizations/{organizationId}/approvals/{approvalId}

> Delete approval flow

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage which actions require an approval process.","name":"organization_approvals"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource."}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}}},"paths":{"/organizations/{organizationId}/approvals/{approvalId}":{"delete":{"operationId":"deleteOrganizationApprovalFlow","responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}},"summary":"Delete approval flow","tags":["organization_approvals"]}}}}
```

## PATCH /organizations/{organizationId}/approvals/{approvalId}

> Update approval flow

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage which actions require an approval process.","name":"organization_approvals"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateApprovalFlow":{"type":"object","title":"UpdateApprovalFlow","additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"type":"string"},"objectType":{"type":"string"},"objectAction":{"type":"string","enum":["create","update","delete"]},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type"]},"minItems":1}}},"approvalStepReviewer":{"type":"object","title":"ApprovalStepReviewer","description":"Reference to an entity that can review the runs for this flow.","additionalProperties":false,"properties":{"type":{"type":"string","enum":["user"]},"id":{"type":"string","format":"uuid"}},"required":["type","id"]},"ApprovalFlow":{"type":"object","title":"ApprovalFlow","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"objectType":{"$ref":"#/components/schemas/objectType"},"objectAction":{"$ref":"#/components/schemas/objectAction"},"steps":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["any","all"]},"users":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"deprecated":true},"reviewers":{"type":"array","items":{"$ref":"#/components/schemas/approvalStepReviewer"},"minItems":1},"message":{"type":"string"}},"required":["type","users"]},"minItems":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/approvalFlowIdentifierTag"}}},"required":["id","ownerId","name","description","objectType","objectAction","steps","createdAt","updatedAt"]},"objectType":{"type":"string","format":"mrn","description":"The identifier of the object"},"objectAction":{"type":"string","enum":["create","update","delete"],"description":"The action performed on the object"},"approvalFlowIdentifierTag":{"type":"object","title":"ApprovalFlowIdentifierTag","description":"A tag that can be used to identify this flow.","additionalProperties":false,"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The HTTP 409 Conflict response status code indicates a request conflict with current state of the target resource."},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/approvals/{approvalId}":{"patch":{"operationId":"updateOrganizationApprovalFlow","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApprovalFlow"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApprovalFlow"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update approval flow","tags":["organization_approvals"]}}}}
```