Uploads
Let a website form send files with the contact it creates: tax documents, photos of an ID, a signed PDF. The files land in the workspace on that contact. Like contacts, this is called from browser JavaScript with a publishable token, and needs no backend of your own.
Read Authentication first for tokens, status codes and origin allowlisting.
Before you start
Section titled “Before you start”Two things have to be true:
- The token holds
files:writeas well ascontacts:write. A workspace admin chooses “Receive files with a contact” when creating the token in Settings, then API. Scopes cannot be added to an existing token, so an older token needs a replacement. - Your site is on the token’s origin allowlist, as for contacts.
The bytes do not go to the API. They go straight to storage, on a different host,
which accepts an upload from any site that holds a signed URL. If your site sends a
Content-Security-Policy, its connect-src has to allow that host as well as the
API’s, or the PUT is blocked by the browser.
How it works
Section titled “How it works”- Post the contact with
"uploads": true. The response carries an upload token. - For each file: reserve it,
PUTthe bytes to the URL you get back, confirm it. - Tell the API you are done.
The upload token is good for one hour and belongs to that one contact. It is not a secret to guard like a password, but it is not the publishable token either: do not hard-code it, and do not reuse it for another visitor.
1. Open an upload session
Section titled “1. Open an upload session”Add uploads: true to the body of POST /api/v1/contacts.
{ "name": "Dana Ruiz", "email": "dana@example.com", "uploads": true }201 Created
{ "ok": true, "id": "j57d8k2m4n6p8q0r2s4t6u8v", "upload": { "token": "erre_up_Q2x...", "expiresAt": 1794000000000, "maxFiles": 20, "maxFileBytes": 26214400, "maxTotalBytes": 209715200 }}expiresAt is a Unix time in milliseconds. Read the three limits from the response
and check files against them before you reserve, so the visitor hears about a file
that is too big before they wait for it.
The contact is saved even when uploads are not available. In that case the
status is still 201 and the body says so:
{ "ok": true, "id": "j57d8k...", "upload": null, "uploadError": "rate_limited" }uploadError |
Meaning |
|---|---|
rate_limited |
Too many upload sessions were opened from this visitor’s network in the last hour. |
session_ended |
You repeated an externalId whose upload session has expired or was completed. See Retries. |
Tell the visitor their details were received and ask them to send the files another way. Do not show an error for the whole form: the lead is already in the CRM.
A token without files:write that sends uploads: true gets 403 forbidden_scope
and nothing is saved, not even the contact.
2. Send each file
Section titled “2. Send each file”Reserve
Section titled “Reserve”POST /api/v1/uploadsAuthorization: Bearer erre_pk_...Content-Type: application/json| Field | Type | Notes |
|---|---|---|
token |
string | Required. The upload token. |
name |
string | Required. The file’s name, up to 200 characters. |
size |
number | Required. The file’s exact size in bytes (file.size). |
contentType |
string | The file’s MIME type (file.type). Empty is fine for unknown types. |
201 Created
{ "ok": true, "fileId": "k97c1...", "uploadUrl": "https://...", "headers": { "Content-Type": "application/pdf", "Content-Disposition": "attachment; filename=\"w2.pdf\"" }, "expiresInSeconds": 600}PUT the bytes
Section titled “PUT the bytes”PUT the file to uploadUrl within ten minutes, sending exactly the headers
from the response and no Authorization header.
The URL was signed for that size and those headers. A different file, a different
Content-Type or a missing Content-Disposition is refused by storage with 403.
Send the File object itself as the body, not a FormData.
Confirm
Section titled “Confirm”POST /api/v1/uploads/confirm{ "token": "erre_up_...", "fileId": "k97c1..." }200 OK with { "ok": true }. The file is saved from this moment. A file you
reserved and never confirmed is not in the workspace and is discarded within the
hour. Confirming twice is harmless.
If the PUT fails
Section titled “If the PUT fails”POST /api/v1/uploads/remove{ "token": "erre_up_...", "fileId": "k97c1..." }This gives the file’s place back, so a retry does not count as a second file. You
can only remove a file you have not confirmed. Once confirmed it belongs to the
workspace, and remove answers 409 file_already_saved.
3. Finish
Section titled “3. Finish”POST /api/v1/uploads/complete{ "token": "erre_up_..." }200 OK
{ "ok": true, "files": 3 }files is how many were saved. The workspace is told about the files at this
point, once, and the upload token stops working. If you never call it, the files
are still saved and the workspace is told about ten minutes after the last one.
The snippet
Section titled “The snippet”A form with name, email and a file input. It is longer than the contacts snippet because every branch here is one a visitor will reach.
<form id="documents-form"> <input name="name" required /> <input name="email" type="email" required /> <input name="files" type="file" multiple /> <button>Send</button> <p id="status"></p></form>
<script> const API = 'https://api.erreos.com/api/v1'; const KEY = 'erre_pk_...'; const statusLine = document.querySelector('#status');
// Once per form fill, outside the handler, so a double click or a retry is the // same submission and gets the same upload token back. const externalId = crypto.randomUUID();
const post = (path, body) => fetch(API + path, { method: 'POST', headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
async function sendFile(token, file) { const reserved = await post('/uploads', { token, name: file.name, size: file.size, contentType: file.type }); if (!reserved.ok) return false; // too big, too many, storage full, or the session ended
const { fileId, uploadUrl, headers } = await reserved.json(); const put = await fetch(uploadUrl, { method: 'PUT', headers, body: file }).catch(() => null); if (!put || !put.ok) { await post('/uploads/remove', { token, fileId }).catch(() => {}); return false; } return (await post('/uploads/confirm', { token, fileId })).ok; }
document.querySelector('#documents-form').addEventListener('submit', async (e) => { e.preventDefault(); const form = new FormData(e.target); const files = form.getAll('files').filter((f) => f.size > 0);
const res = await post('/contacts', { name: form.get('name'), email: form.get('email'), externalId, uploads: files.length > 0 }); if (!res.ok) { // NOTHING was saved. Show the visitor an error and log this. console.error('ErreOS ingest failed', res.status, await res.json()); statusLine.textContent = 'Something went wrong. Please try again.'; return; }
const { upload } = await res.json(); if (files.length === 0) { statusLine.textContent = 'Thank you. We received your details.'; return; } if (!upload) { // The contact WAS saved and the files were NOT sent. statusLine.textContent = 'We received your details, but could not take your files. Please email them to us.'; return; }
const failed = []; for (const file of files) { statusLine.textContent = 'Sending ' + file.name + '...'; const tooBig = file.size > upload.maxFileBytes; if (tooBig || !(await sendFile(upload.token, file))) failed.push(file.name); } await post('/uploads/complete', { token: upload.token }).catch(() => {});
statusLine.textContent = failed.length === 0 ? 'Thank you. We received your files.' : 'We could not receive: ' + failed.join(', ') + '. Please email those to us.'; });</script>The three status messages are not optional. There are three different outcomes and a visitor who sent tax documents needs to know which one happened: nothing was saved, the contact was saved without files, or some files did not arrive.
Files go one at a time on purpose. A phone on a weak connection finishes more of them that way than it does with five uploads competing.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Files per submission | 20 |
| One file | 25 MB |
| All files of one submission | 200 MB |
| Upload token lifetime | 1 hour |
| Signed upload URL lifetime | 10 minutes |
| Upload sessions per network | 6 an hour, per token |
| Upload calls | 120 a minute, per token |
| Total reserved through a token | 2 GB a day |
The limits in the contact response (maxFiles, maxFileBytes, maxTotalBytes)
are the ones to code against. If these numbers change, the response changes with
them and this table may lag.
The daily total is the one limit that turns visitors away. It exists because a
publishable token is public, and without it anyone who copied the token could fill
the workspace’s storage. When it is spent, reserving a file answers 429 until the
day rolls over. Contacts are still saved. If a site reaches it with real traffic,
tell ErreOS.
Errors on the upload routes
Section titled “Errors on the upload routes”The codes in Authentication apply here too. These are the ones specific to uploads:
| Status | Code | What to do |
|---|---|---|
400 |
invalid_field |
name, size, token or fileId is missing or the wrong type. |
400 |
unknown_field |
You sent a field this route does not accept. |
404 |
unknown_file |
That fileId is not one this upload token reserved, or it was already removed. |
409 |
too_many_files |
The submission already holds 20 files. |
409 |
upload_allowance_exceeded |
This file would take the submission past 200 MB. |
409 |
too_many_attempts |
The token reserved and removed too many times. Start a new submission. |
409 |
file_already_saved |
remove only. The file was confirmed. |
410 |
upload_session_ended |
The upload token is unknown, expired or completed. Stop sending. Confirmed files are saved. |
413 |
file_too_large |
The file is over 25 MB. |
429 |
rate_limited |
Too many calls, or the token’s daily total is spent. Retry-After says how long, in seconds. |
507 |
storage_full |
The workspace’s storage is full. Nothing you can fix from the site; tell the visitor to email. |
For a visitor, every one of these means the same thing: this file did not arrive. The snippet treats them alike for that reason. Log the code so you can tell them apart later.
Retries
Section titled “Retries”Send the same externalId again with uploads: true and you get the same contact
and, if its hour is not over, the same upload token. That is what makes a
retried submit safe: the form carries on where it stopped.
Two consequences:
- Generate
externalIdwithcrypto.randomUUID(), once per form fill. Do not use the visitor’s email or phone. Anyone who can guess anexternalIdcan get its upload token while the hour lasts. - A repeated
externalIdnever opens a new session. After the hour, or aftercomplete, the answer is"upload": nullwith"uploadError": "session_ended". To send more files later, the visitor fills the form again, which creates a new contact.
What the workspace sees
Section titled “What the workspace sees”The files are in the contact’s own folder in Files, and on the contact’s Files tab. Each one shows the contact as its sender.
The people who are told about a new contact from the website are also told about its files: one notice per submission, naming the contact and how many files arrived. A submission that sent no file adds no second notice.
Nothing is ever attached to a contact that already existed, even when the email matches. A typed email proves nothing about who typed it.