Create a verification

The address to verify and the name of who lives or works there.

How the person confirms the code. It also sets what is printed on the letter.

Possible values

• hosted_page: The person confirms on a page with your brand, hosted by CartaFlow: through the QR code, which opens the page with the code already in it, or by typing the code at the printed address. You build no screens; the result arrives by webhook and shows in the dashboard.
• code: The letter carries only the code, with no QR code and no page address. The person types it into your website or app, and your server checks it with POST /v1/verifications/{verification_id}/check.

Customizes the CartaFlow letter template, for this verification only. Each field you leave out comes from your company’s default letter, saved in the dashboard, and, when the company has not saved one, from the CartaFlow default. The texts sit below the envelope window. The default texts and the fixed parts, such as "Seu código" ("Your code") and the QR code instruction, are in Portuguese. Your logo, your company name, the address and the code are always printed and are not changed here. Do not use it together with document: the API answers 422 with invalid_value.

Your own PDF, instead of the CartaFlow letter template. Pick the way with the type field: url (up to 10 MB), upload (a file sent beforehand with POST /v1/uploads, up to 10 MB) or base64 (up to 3 MB). This endpoint only takes JSON: to send the file itself, use the two-step upload.

The PDF follows the rules of a letter (A4 portrait, up to 6 sheets, blank address area with address_placement: first_page, selectable text) and has reserved markers that CartaFlow fills in:

• {{OTP_CODE}}: required. Where the code is printed, as 123 456, in the marker’s font, size and color. Without it, the API answers 422 with otp_code_missing.
• {{VERIFICATION_URL}}: optional. The address of the confirmation page (hosted_page_url), without the code.
• {{QR_CODE}}: optional. A 25 x 25 mm QR code that opens the page with the code already in it. Its top-left corner sits where the marker starts: leave that space blank, to the right of and below the marker.

{{VERIFICATION_URL}} and {{QR_CODE}} only work with method: hosted_page; with method: code, the API answers 422 with invalid_value. Type the markers in capitals, with the braces. Other markers, such as {{name}}, work as in a letter: send their values in variables, leaving out the reserved ones (variable_not_found).

true prints in color. false prints in black and white: a color PDF comes out in grayscale. Color printing costs extra per printed page (each printed side counts as a page). Only applies with document, your own PDF. The CartaFlow letter template is always one sheet in black and white: without document, sending this field with a value other than the default gives a 422 with invalid_value.

true prints on both sides: each sheet carries two pages of the document, so the letter uses fewer sheets and costs less. false prints on the front of each sheet only. Only applies with document, your own PDF. The CartaFlow letter template is always one sheet in black and white: without document, sending this field with a value other than the default gives a 422 with invalid_value.

Where CartaFlow prints the recipient’s address on your PDF. Only applies with document, your own PDF. The CartaFlow letter template is always one sheet in black and white: without document, sending this field with a value other than the default gives a 422 with invalid_value.

Possible values

• first_page: In the address area of your document’s first page (90 x 45 mm, 20 mm from the left and 45 mm from the top). That area must be blank in your PDF. Default.
• extra_page: On a side of its own, the first one, which shows through the envelope window. Use it when your layout fills the address area. It takes a side that would otherwise be blank, when there is one: the back of the first page when printing on one side, or the spare side of a double-sided document with an odd number of pages. A double-sided document with an even number of pages gets one more sheet at the front. The address is never charged.

Text printed right below the code, on the CartaFlow letter template, telling the person where to type it. Use it with method: code, for example "Open the app, go to Profile > Address and type the code". It is also printed with method: hosted_page when letter turns off both the QR code and the page address. If you leave it out, we print "Digite este código no site ou aplicativo de" ("Type this code on the website or app of") followed by your company name. It is not printed on your own PDF: write the instruction in the document. Up to 300 characters.

Only for method: hosted_page. After confirming, the page shows a button that takes the person to this URL, such as the logged-in area of your site.

Your identifier for this verification, such as the invoice number or the customer id in your system. Shown in the dashboard and usable as a filter when listing. It does not have to be unique. Up to 100 characters.

Key-value pairs to store your own data with the object, such as your customer or contract id. Returned in every response and webhook and never printed. Up to 20 keys; keys up to 40 characters and string values up to 500 characters. Do not store sensitive data such as passwords or card numbers.