# Reuse and capture of documents

{% hint style="info" %}
**URL Base**:

* UAT: <mark style="color:blue;">`https://api.id.uat.unico.app`</mark>.
* Production: <mark style="color:blue;">`https://api.id.unico.app`</mark>.
  {% endhint %}

## Get Reusable Documents

> Endpoint to get a user's documents for reuse in by Client.

```json
{"openapi":"3.0.0","info":{"title":"GetReusableDocuments","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/documents/v1":{"get":{"summary":"Get Reusable Documents","description":"Endpoint to get a user's documents for reuse in by Client.","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"},"description":"User identifier value (e.g., CPF value)."},{"name":"type","in":"query","required":true,"schema":{"type":"string"},"description":"Document type (e.g., BR_CPF)."},{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Valid access-token."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"Valid APIKEY with the capabilitie Document Capture and Reuse enabled."}],"responses":{"200":{"description":"Process information retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"List of documents associated with the process.","items":{"type":"object","properties":{"documentType":{"type":"string","enum":["unico.moja.dictionary.br.rg.v2.Rg","unico.moja.dictionary.br.cnh.v2.Cnh","unico.moja.dictionary.br.cin.v1.Cin","unico.moja.dictionary.br.passaporte.v1.Passaporte"],"description":"Document type."},"documentId":{"type":"string","description":"Document ID."}}}}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"404":{"description":"Not Found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"Ddscription":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="info" %}

* The use of the Reuse feature requires a prior Identity Verification process, which must yield a "YES" response or a risk score equal to or greater than +50; otherwise, it will be necessary to capture the user's document.
* If you find a document to be reused, in the process creation endpoint you will enter the ID of this document in the `document.documentId` parameter and it will not be necessary to capture the document and send the base64 in the `document.files` parameter.
* **If no document is found to be reused,** the request will still succeed (**200 OK**), but the response will contain the following content:

```json
{
  "items": [{}]
}
```

{% endhint %}

## Create a Document Process

> Endpoint to create a new Document process by Client.

```json
{"openapi":"3.0.0","info":{"title":"CreateProcess by Client","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/processes/v1":{"post":{"summary":"Create a Document Process","description":"Endpoint to create a new Document process by Client.","parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Valid access token."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"Valid APIKEY with the capabilitie Document Capture and Reuse enabled."}],"requestBody":{"description":null,"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","document"],"properties":{"subject":{"type":"object","description":"User information.","required":["code","name"],"properties":{"code":{"type":"string","description":"User's CPF. Must contain 11 characters and be sent without dots or dashes."},"name":{"type":"string","description":"User's name."},"gender":{"type":"string","description":"User's gender. Possible values: 'M' for male or 'F' for female."},"birthDate":{"type":"string","description":"User's birth date. Must be in ISO 8601 format (yyyy-MM-dd)."},"email":{"type":"string","description":"User's email."},"phone":{"type":"string","description":"User's phone number. It must contain 13 characters and be sent without dots or dashes, in the standard DDI + DDD + Telephone number."}}},"document":{"type":"object","description":"Information about the document to be captured.","required":["purpose","authProcessId"],"properties":{"purpose":{"type":"string","enum":["creditprocess","carpurchase","paybypaycheck","onboarding","fgts"],"description":"Indicates the purpose of the document sharing. Possible values: 'creditprocess'; 'carpurchase'; 'paybypaycheck'; 'onboarding'; 'fgts'."},"authProcessId":{"type":"string","description":"ID of the biometric process that must have been previously performed through the Identity Verification capability. The ID must belong to a process completed with a valid biometric and used within 24 hours after the process is finished."},"documentId":{"type":"string","description":"The identifier of the document to be reused. You will find it when using the endpoint to query documents for reuse. If no document is found for reuse, the document must be captured and sent as base64 in the `document.files` parameter."},"files":{"type":"array","description":"Base64 of the user's document if it does not find one to be reused in the endpoint to query documents to be reused. The array can contain 1 file (e.g.: full CNH) or 2 files (e.g.: CNH front and CNH back).","items":{"type":"object","properties":{"data":{"type":"string","description":"Base64 encoded document image."}}}}}}}}}}},"responses":{"200":{"description":"Process information successfully retrieved.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","enum":[3,5],"description":"Process status. Possible values: '3' - Completed; '5' - Error."},"document":{"type":"object","description":"Document information.","properties":{"id":{"type":"string","description":"Document ID."},"type":{"type":"string","description":"Document type.","enum":["unico.moja.dictionary.br.rg.v2.Rg","unico.moja.dictionary.br.cnh.v2.Cnh","unico.moja.dictionary.br.cin.v1.Cin","unico.moja.dictionary.br.passaporte.v1.Passaporte"]},"cpfMatch":{"type":"boolean","description":"Indicates if the CPF on the document matches the CPF provided during process creation."},"faceMatch":{"type":"boolean","description":"Indicates whether the face on the document matches the face captured during the process creation."},"content":{"type":"object","description":"Object containing the fields extracted from the document after the OCR extraction process.","properties":{"numero":{"type":"string","description":"Document number."},"rgNumero":{"type":"string","description":"RG number."},"nomeCivil":{"type":"string","description":"Full name of the holder."},"filiacao":{"type":"array","items":{"type":"string"},"description":"Holder's parents' names."},"dataNascimento":{"type":"string","format":"date-time","description":"Holder's date of birth."},"dataHabilitacao":{"type":"string","format":"date-time","description":"Holder's license issuance date."},"dataExpiracao":{"type":"string","format":"date-time","description":"Document expiration date."},"dataEmissao":{"type":"string","format":"date-time","description":"Document issuance date."},"localEmissao":{"type":"string","description":"Document issuance location."},"categoria":{"type":"string","description":"Document category."},"renachNumero":{"type":"string","description":"RENACH number."}}},"fileUrls":{"type":"array","items":{"type":"string"},"description":"URLs of the document files."}}}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="warning" %}
**Important**:

* To use the **Document Capture and Reuse** capability, the **Identity Verification** capability must be used beforehand, as it is necessary to include the `processId` obtained from the Identity Verification in the `document.authProcessId` parameter:
  * The process must have valid biometrics, be used within 24 hours of completion and cannot be reused.
  * It is possible to reuse a biometric authentication previously performed by the same user within a period of up to 24 hours. Within this timeframe, the ID authentication proof can be used in different document verification processes (e.g., RG and CNH) without the need for a new biometric authentication.
* If we are unable to extract a field from the document, it is not listed in the API return.
* The link returned in `fileUrls` is valid for 10 minutes. A GET request must be made during the process to refresh the link and extend its validity.
* When using the **Document Capture and Reuse** feature, it is **`mandatory`** to inform the user, on the interface, about the reuse, as required by the contract.
* If an error occurs during processing, the process will return a `status = 5`, as shown in the example below:
* ```json
    {
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 5
    }
  ```

{% endhint %}

**Content returned in document.content based on document.type**:

{% tabs %}
{% tab title="CNH" %}

* Type: CNH
* Content: Brazilian National Driving License
  * String numero;
  * String rgNumero;
  * String cpfNumero;
  * String nomeCivil;
  * List string filiacao;
  * Datetime dataNascimento;
  * Datetime data\_habilitacao;
  * Datetime data\_expiracao;
  * Datetime data\_emissao;
  * String local\_emissao;
  * String categoria;
  * String renachNumero;

```json
"content": {
    "numero": "044589731564",
    "rgNumero": "123456789 SESP PR",
    "nomeCivil": "Homer Simpson",
    "filiacao": [
        "Monasimpson",
        "Monasimpson"
    ],
    "dataNascimento": "1990-05-12T00:00:00Z",
    "dataHabilitacao": "1997-11-18T00:00:00Z",
    "dataExpiracao": "2017-12-07T00:00:00Z",
    "dataEmissao": "2012-12-07T00:00:00Z",
    "localEmissao": "Curitiba PR",
    "categoria": "B",
    "renachNumero": "PR904987581"
}
```

{% endtab %}

{% tab title="RG" %}

* Type: RG
* Content: Brazilian General Registration
  * String numero;
  * String orgao\_emissor;
  * String uf\_emissor;
  * String cpfNumero;
  * String carteira\_profissionalNumero;
  * String certificado\_militarNumero;
  * String cnsNumero;
  * String nis\_pis\_pasepNumero;
  * String ctpsNumero;
  * String ctps\_serie;
  * String ctps\_uf;
  * String titulo\_eleitorNumero;
  * String nomeCivil;
  * String nome\_social;
  * List string filiacao;
  * Datetime dataNascimento;
  * String naturalidade;
  * Datetime data\_emissao;

```json
"content": {
    "dataEmissao": "2012-12-21T02:00:00Z",
    "dataNascimento": "1980-12-19T03:00:00Z",
    "filiacao": [
     "Rosa Coelho Da Costa",
     "Edivaldo Da Costa",
     "Rosa Coelho Da Costa",
     "Edivaldo Da Costa"
    ],
    "naturalidade": "Sao Paulo SP",
    "nomeCivil": "Daniel Coelho Da Costa",
    "numero": "4815162342",
    "orgaoEmissor": "Secretaria Da Segurança Pública (SSP)",
    "ufEmissor": "UF_SP"
}
```

{% endtab %}

{% tab title="CIN" %}

* Type: CIN
* Content: Brazilian national Identity Card
  * string rgNumero;
  * string cpfNumero;
  * string nomeCivil;
  * string nome\_social;
  * List string filiacao;
  * Datetime dataNascimento;
  * Datetime data\_expiracao;
  * Datetime data\_emissao;
  * string orgao\_emissor;
  * string local\_emissao;
  * string naturalidade;
  * string nacionalidade;

```json
"content": {
    "nomeCivil": "Vitor Ra",
    "nomeSocial": "Vitor Ra",
    "filiacao": [
        "Danilo Luis Renan Ramos",
        "Giovanna Vitoria",
        "Danilo Luis Renan Ramos",
        "Giovanna Vitoria"
    ],
    "dataExpiracao": "2034-03-02T00:00:00Z",
    "dataEmissao": "2024-03-02T00:00:00Z",
    "orgaoEmissor": "Detran/Rj",
    "localEmissao": "Rio De Janeiro RJ",
    "naturalidade": "Rio De Janeiro RJ",
    "nacionalidade": "BRA"
}
```

{% endtab %}

{% tab title="Passport" %}

* Type: PASSAPORTE
* Content: Brazilian Passport
  * string numero;
  * string nome;
  * string sobrenome;
  * string pais\_emissor;
  * string nacionalidade;
  * string naturalidade;
  * Datetime data\_nascimento;
  * Datetime data\_emissao;
  * Datetime data\_expiracao;
  * string autoridade.

```json
"content": {
            "numero": "AA011906",
            "nome": "CHANCHÃO AMARELO",
            "sobrenome": "PASSAREDO",
            "paisEmissor": "BRA",
            "nacionalidade": "BRASILEIRO(A)",
            "naturalidade": "<nil>",
            "dataNascimento": "1920-06-01T00:00:00Z",
            "dataEmissao": "2000-01-01T00:00:00Z",
            "dataExpiracao": "2010-01-01T00:00:00Z",
            "autoridade": "SR/DPF/DF"
        }
```

{% endtab %}

{% tab title="UNKNOWN" %}

* Type: UNKNOWN
* Content: Unknown document.&#x20;

```
content {
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Tips**:

* To implement your business rules, always validate the final statuses of the processes (`3`, `5`). To validate the response from the IDCloud capabilities, only consider `status = 3` for your decision-making.
  {% endhint %}

### Errors

{% tabs %}
{% tab title="400 Bad Request" %}

<table><thead><tr><th width="110" align="center">Code</th><th width="290">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>20900</code></td><td><code>O base64 informado não é válido.</code></td><td>The base64 parameter is invalid. Possible causes: It's not an image or it's an injection attempt.</td></tr><tr><td align="center"><code>20807</code></td><td><code>A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.</code></td><td>The resolution of the uploaded image is too low.</td></tr><tr><td align="center"><code>20507</code></td><td><code>O parâmetro subject.code é inválido.</code></td><td>Non-standard or non-existent CPF.</td></tr><tr><td align="center"><code>20506</code></td><td><code>O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.</code></td><td>When the base64 is too large. The image can be compressed to JPEG92 without loss of quality.</td></tr><tr><td align="center"><code>20505</code></td><td><code>O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.</code></td><td>When the base64 entered is not a valid Base64. Possible causes: not a valid image or invalid prefix.</td></tr><tr><td align="center"><code>20009</code></td><td><code>O parâmetro imagebase64 não foi informado.</code></td><td>The imagebase64 parameter, which contains the person's selfie, is missing.</td></tr><tr><td align="center"><code>20006</code></td><td><code>O parâmetro subject.name não foi informado.</code></td><td>The subject.name parameter, which contains the person's name, is missing.</td></tr><tr><td align="center"><code>20005</code></td><td><code>O parâmetro subject.code não foi informado.</code></td><td>The subject.code parameter, which contains the person's cpf, is missing.</td></tr><tr><td align="center"><code>20004</code></td><td><code>O parâmetro subject não foi informado.</code></td><td>The subject parameter, which contains the person's data (cpf, name), is missing.</td></tr><tr><td align="center"><code>20003</code></td><td><code>The request body is missing or invalid.</code></td><td>Null or invalid payload.</td></tr><tr><td align="center"><code>20002</code></td><td><code>O parâmetro APIKey não foi informado.</code></td><td>The APIKEY parameter is missing from the request header.</td></tr><tr><td align="center"><code>20001</code></td><td><code>O parâmetro authtoken não foi informado</code></td><td>The integration token parameter is missing from the request header.</td></tr><tr><td align="center"><code>10508</code></td><td><code>The JWT with the captured face has already been used.</code></td><td>The jwt can only be used once.</td></tr><tr><td align="center"><code>10507</code></td><td><code>The JWT with the captured face is expired.</code></td><td>JWT expired. The .jwt must be sent within 10 minutes.</td></tr><tr><td align="center"><code>10506</code></td><td><code>The bundle is invalid.</code></td><td>Invalid bundle. APIKEY uses a security method and this request does not meet the security requirements (SDK).</td></tr></tbody></table>
{% endtab %}

{% tab title="403 Forbidden" %}

<table><thead><tr><th width="183" align="center">Code</th><th>Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>30017</code></td><td><code>Jwt header is an invalid JSON.</code></td><td>When the access-token used contains wrong characters.</td></tr><tr><td align="center"><code>10502</code></td><td><code>O token informado está expirado.</code></td><td>When the access-token used has expired</td></tr><tr><td align="center"><code>10501</code></td><td><code>O token informado é inválido.</code></td><td>The authentication token is invalid.</td></tr><tr><td align="center"><code>10201</code></td><td><code>O AppKey informado é inválido.</code></td><td>The APIKEY parameter has not been entered or does not exist.</td></tr></tbody></table>
{% endtab %}

{% tab title="500 Internal Server Error" %}

<table><thead><tr><th width="99" align="center">Code</th><th width="299">Message</th><th>Description</th></tr></thead><tbody><tr><td align="center"><code>99999</code></td><td><code>Internal failure! Try again later</code></td><td>When there is an internal error.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idcloud/by-client-integration/by-client-api/api-reference/reuse-and-capture-of-documents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.