Skip to Content

Change a recipient

PATCH
/v1/ec/recipients/{identification}

Changes their name, email, phone or address: only what you send. A phone you give wins over the one their documents carry.

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.

Path Parameters

identification*string
Length1 <= length <= 20

Header Parameters

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
name?string
Match^[^\n\r]*$
Length1 <= length <= 300
email?|

null clears it.

Formatemail
phone?|

null clears it.

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

null clears it.

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

Response Body

The recipient

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 PATCH 'https://api.fiscalbase.io/v1/ec/recipients/string' \
  -H 'Content-Type: application/json' \
  -d '{}'
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"
    ]
  }
}