Save a recipient
Saves a person or company before any document names them, such as a customer at the counter whose invoice comes later. They are listed and retrieved like any recipient, with no sales yet. The documents you issue to them afterwards keep the name and email they carry, as for every recipient.
AuthorizationBearer <token>Your API key, which acts for the one business it was created for: fb_live_… keys work at api.fiscalbase.io and issue in live, and fb_sandbox_… keys work at api-sandbox.fiscalbase.io and issue in sandbox, on the simulated SRI. A key sent to the other host is refused with api_key_wrong_host, which names its host.
idempotency-key?stringSend the same key to retry safely: a repeat of the same request answers what the first answered, without doing it again. Keys are scoped to your key's business and environment; the same key with another request is 409 idempotency_key_reused.
1 <= length <= 255Fiscalbase-Environment?stringThe environment the call acts in. Required with a person's session; a key's own environment is the one that counts, so a key may leave it out, and naming another is 422 environment_mismatch.
"sandbox""test""live"Fiscalbase-Business?stringThe business the call acts for. With a person's session, the one the call is about (without it, a call about one business is 422 business_required and a list covers every business of the organization); a key acts for its own, so naming another is 422 business_mismatch.
uuidFiscalbase-Channel?stringWhich of Fiscalbase's own integrations a key's call comes from, recorded as the channel of the documents it issues: a record, not a permission. Without it, api. A person's call is always console.
"api""mcp"Fiscalbase-Agent?stringThe AI agent a key's call comes from, as its client names itself (the MCP server sets it); recorded with the request and shown in the console's request log.
application/json- body
identification*stringTheir RUC (13 digits) or cedula (10), validated.
name*stringTheir legal name, or full name.
^[^\n\r]*$1 <= length <= 300email?stringWhere their documents are emailed.
emailphone?stringDigits only, from 7 to 15, with a leading + if it carries a country code: 0991234567 or +593991234567.
^\+?\d{7,15}$address?stringTheir address, up to 300 characters. An invoice issued to them carries it as the buyer's address when the request does not name one.
^[^\n\r]*$1 <= length <= 300Saved
application/json- response
id*stringuuidobject*"recipient""recipient"environment*string"sandbox""test""live"business_id*stringThe business that issued to them.
uuididentification*stringname*stringAs their most recent document names them.
email*|The email for their documents: the latest one any document gave. null if none carries one.
currency*stringThe currency of year_total and sales_total.
^[A-Z]{3}$year_count*integerAuthorized documents in their name this year, on their country's calendar.
year_total*stringSales this year: invoices and debit notes minus credit notes, with cents, in the recipient's currency. Withholdings, delivery notes and purchase settlements do not add up.
sales_total*stringTotal sales across all years, with the same rule as year_total: authorized invoices and debit notes minus credit notes, with cents.
address*|The address you saved for this customer, or null. An invoice issued to them carries it as the buyer's address when the request does not name one.
phone*|The phone number carried in the additional information (Teléfono, Celular) of their most recent document that has one; documents have no phone field of their own. null if none carries it.
email_bounced*booleantrue if an email of a document to this address bounced for good (the address does not exist) or its owner marked it as spam, according to the email provider: their documents are not reaching them.
last_issue_date*|The issue date of their latest authorized document.
datesri_status*|What the SRI records for their RUC: active, or review if it is not active or the SRI flags it. null until it has been looked up (GET /v1/ec/taxpayers/{identification}) or if they have no RUC.
"active""review"nullcreated_at*stringWhen you issued their first document.
date-timeupdated_at*stringWhen a document last named them, with its name and email.
date-timeyear*curl -X POST 'https://api.fiscalbase.io/v1/ec/recipients' \
-H 'Content-Type: application/json' \
-d '{
"identification": "string",
"name": "string"
}'{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"object": "recipient",
"environment": "sandbox",
"business_id": "f59fcbb7-848d-4242-af07-a8bb7e3ab37c",
"identification": "string",
"name": "string",
"email": "string",
"currency": "string",
"year_count": 0,
"year_total": "string",
"sales_total": "string",
"address": "string",
"phone": "string",
"email_bounced": true,
"last_issue_date": "2019-08-24",
"sri_status": "active",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"year": {
"year": 0,
"count": 0,
"currency": "string",
"total": "string",
"by_type": {
"invoice": 0,
"credit_note": 0,
"debit_note": 0,
"withholding": 0,
"delivery_note": 0,
"purchase_settlement": 0
},
"by_month": [
"string"
]
}
}Search your business's recipients GET
The people and companies your key's business has issued documents to in its environment, most recent first: they are added on their own when you issue or import. `q` searches by name or identification; `counts` counts its recipients without filtering.
Retrieve a recipient GET
A recipient by their RUC or `cedula`, with what you have sold them this year by document type and by month.