Skip to Content

Save a recipient

POST
/v1/ec/recipients

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.

Authorization

headerAuthorizationBearer <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.

Header Parameters

idempotency-key?string

Send 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.

Length1 <= length <= 255
Fiscalbase-Environment?string

The 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.

Value in"sandbox""test""live"
Fiscalbase-Business?string

The 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.

Formatuuid
Fiscalbase-Channel?string

Which 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.

Value in"api""mcp"
Fiscalbase-Agent?string

The 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.

Request Body

application/json
  1. body
identification*string

Their RUC (13 digits) or cedula (10), validated.

name*string

Their legal name, or full name.

Match^[^\n\r]*$
Length1 <= length <= 300
email?string

Where their documents are emailed.

Formatemail
phone?string

Digits only, from 7 to 15, with a leading + if it carries a country code: 0991234567 or +593991234567.

Match^\+?\d{7,15}$
address?string

Their address, up to 300 characters. An invoice issued to them carries it as the buyer's address when the request does not name one.

Match^[^\n\r]*$
Length1 <= length <= 300

Response Body

Saved

application/json
  1. response
id*string
Formatuuid
object*"recipient"
Value in"recipient"
environment*string
Value in"sandbox""test""live"
business_id*string

The business that issued to them.

Formatuuid
identification*string
name*string

As their most recent document names them.

email*|

The email for their documents: the latest one any document gave. null if none carries one.

currency*string

The currency of year_total and sales_total.

Match^[A-Z]{3}$
year_count*integer

Authorized documents in their name this year, on their country's calendar.

year_total*string

Sales 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*string

Total 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*boolean

true 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.

Formatdate
sri_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.

Value in"active""review"null
created_at*string

When you issued their first document.

Formatdate-time
updated_at*string

When a document last named them, with its name and email.

Formatdate-time
year*
Example Request
curl -X POST 'https://api.fiscalbase.io/v1/ec/recipients' \
  -H 'Content-Type: application/json' \
  -d '{
  "identification": "string",
  "name": "string"
}'
Example Response
{
  "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"
    ]
  }
}