---
updatedAt: 2026-05-14T14:32:15.000Z
agentTools:
  projectIndex: https://docs.oysterhr.com/v0.1/llms.txt
---

# Submit an approved partner identity verification

Submits a successful verification result for Partner KYC, allowing you to send relevant information from your identity provider.

Note: Access to the partner KYC process is restricted. Please reach out to api-support@oysterhr.com so we can evaluate your eligibility.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Endpoints",
    "version": "v0.1"
  },
  "components": {
    "securitySchemes": {
      "bearer_auth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "autoKycVerificationData": {
        "type": "object",
        "properties": {
          "sessionUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "sessionUrl"
        ]
      },
      "partnerKycVerificationData": {
        "type": "object",
        "properties": {
          "referenceId": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "user": {
            "type": "object",
            "properties": {
              "firstName": {
                "type": "string"
              },
              "middleName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              },
              "dateOfBirth": {
                "type": "string",
                "format": "date"
              }
            },
            "required": [
              "firstName",
              "lastName",
              "dateOfBirth"
            ]
          },
          "document": {
            "type": "object",
            "properties": {
              "countryCode": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "number": {
                "type": "string"
              },
              "expirationDate": {
                "type": "string",
                "format": "date"
              },
              "issuanceDate": {
                "type": "string",
                "format": "date"
              }
            },
            "required": [
              "countryCode",
              "type",
              "number"
            ]
          },
          "screening": {
            "type": "object",
            "properties": {
              "pep": {
                "type": "boolean"
              },
              "sanctions": {
                "type": "boolean"
              }
            },
            "required": [
              "pep",
              "sanctions"
            ]
          }
        },
        "required": [
          "referenceId",
          "user",
          "document",
          "screening"
        ]
      },
      "identityVerification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "IN_PROGRESS",
              "RESUBMISSION_REQUIRED",
              "APPROVED",
              "DECLINED"
            ]
          },
          "verificationData": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/autoKycVerificationData"
              },
              {
                "$ref": "#/components/schemas/partnerKycVerificationData"
              },
              {
                "type": "object",
                "properties": {}
              }
            ]
          }
        },
        "required": [
          "id",
          "status",
          "verificationData"
        ]
      }
    }
  },
  "paths": {
    "/v0.1/engagements/{id}/identity_verification/approved": {
      "post": {
        "summary": "Submit an approved partner identity verification",
        "tags": [
          "Identity Verification"
        ],
        "description": "Submits a successful verification result for Partner KYC, allowing you to send relevant information from your identity provider.\n\nNote: Access to the partner KYC process is restricted. Please reach out to api-support@oysterhr.com so we can evaluate your eligibility.\n",
        "security": [
          {
            "bearer_auth": [
              "manage"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Engagement ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully created approved partner verification",
            "content": {
              "application/json": {
                "examples": {
                  "Successfully created approved partner verification": {
                    "value": {
                      "data": {
                        "id": "A12b9d08",
                        "status": "APPROVED",
                        "verificationData": {
                          "referenceId": "unique_id_123",
                          "user": {
                            "firstName": "John",
                            "middleName": "Smith",
                            "lastName": "Doe",
                            "dateOfBirth": "1990-01-01"
                          },
                          "document": {
                            "countryCode": "NL",
                            "type": "passport",
                            "number": "123456789",
                            "expirationDate": "2030-08-02",
                            "issuanceDate": "2025-08-02"
                          },
                          "screening": {
                            "pep": false,
                            "sanctions": false
                          }
                        }
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/identityVerification"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity -- Engagement must have accepted the invitation first",
            "content": {
              "application/json": {
                "examples": {
                  "Unprocessable Entity -- Engagement must have accepted the invitation first": {
                    "value": {
                      "errors": [
                        {
                          "message": "Engagement must have accepted the invitation first."
                        }
                      ]
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "example": "Engagement must have accepted the invitation first."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "referenceId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Unique reference ID for this verification from the partner",
                    "example": "unique_id_123"
                  },
                  "reason": {
                    "nullable": true,
                    "type": "string",
                    "description": "Optional reason for the approval",
                    "example": "Documents verified successfully"
                  },
                  "user": {
                    "type": "object",
                    "properties": {
                      "firstName": {
                        "type": "string",
                        "minLength": 1
                      },
                      "middleName": {
                        "nullable": true,
                        "type": "string"
                      },
                      "lastName": {
                        "type": "string",
                        "minLength": 1
                      },
                      "dateOfBirth": {
                        "type": "string",
                        "format": "date",
                        "minLength": 1
                      }
                    },
                    "required": [
                      "firstName",
                      "lastName",
                      "dateOfBirth"
                    ]
                  },
                  "document": {
                    "type": "object",
                    "properties": {
                      "countryCode": {
                        "type": "string",
                        "minLength": 1
                      },
                      "type": {
                        "type": "string",
                        "minLength": 1
                      },
                      "number": {
                        "type": "string",
                        "minLength": 1
                      },
                      "expirationDate": {
                        "nullable": true,
                        "type": "string",
                        "format": "date"
                      },
                      "issuanceDate": {
                        "nullable": true,
                        "type": "string",
                        "format": "date"
                      }
                    },
                    "required": [
                      "countryCode",
                      "type",
                      "number"
                    ]
                  },
                  "screening": {
                    "type": "object",
                    "properties": {
                      "pep": {
                        "type": "boolean"
                      },
                      "sanctions": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "pep",
                      "sanctions"
                    ]
                  }
                },
                "required": [
                  "referenceId",
                  "user",
                  "document",
                  "screening"
                ]
              },
              "examples": {
                "Successfully created approved partner verification": {
                  "summary": "Successfully created approved partner verification",
                  "value": {
                    "referenceId": "unique_id_123",
                    "user": {
                      "firstName": "John",
                      "middleName": "Smith",
                      "lastName": "Doe",
                      "dateOfBirth": "1990-01-01"
                    },
                    "document": {
                      "countryCode": "NL",
                      "type": "passport",
                      "number": "123456789",
                      "expirationDate": "2030-08-02",
                      "issuanceDate": "2025-08-02"
                    },
                    "screening": {
                      "pep": false,
                      "sanctions": false
                    }
                  }
                }
              }
            }
          },
          "required": true
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.oysterhr.com",
      "description": "Production server"
    },
    {
      "url": "https://api-sandbox.oysterhr.com",
      "description": "Sandbox server"
    }
  ],
  "tags": [
    {
      "name": "Identity Verification",
      "description": "The Identity Verification API manages identity verification for engagements via two workflows: Oyster KYC (managed by Oyster via Oyster's identity provider) and Partner KYC (managed by the partner's identity provider)."
    }
  ]
}
```