Skip to content

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.

Two things have to be true:

  1. The token holds files:write as well as contacts: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.
  2. 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.

  1. Post the contact with "uploads": true. The response carries an upload token.
  2. For each file: reserve it, PUT the bytes to the URL you get back, confirm it.
  3. 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.

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.

POST /api/v1/uploads
Authorization: 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 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.

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.

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.

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.

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.

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.

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.

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 externalId with crypto.randomUUID(), once per form fill. Do not use the visitor’s email or phone. Anyone who can guess an externalId can get its upload token while the hour lasts.
  • A repeated externalId never opens a new session. After the hour, or after complete, the answer is "upload": null with "uploadError": "session_ended". To send more files later, the visitor fills the form again, which creates a new contact.

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.