Get a proforma
Scope: sales:proforms.read https://api.alladdin.com/api/v2/proformas/{proformaId}
Retrieves the full details of a single proforma invoice by its unique identifier.
The response includes line items, custom fields, pipeline stage, and the source document if the proforma was converted from another document.
Parameters
Path parameters
proformaId string required
Proforma ID (24-char hex ObjectId)
Request
import requests
url = "https://api.alladdin.com/api/v2/proformas/{proformaId}"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"id": "507f1f77bcf86cd799439011",
"document_number": "INV-0001",
"contact_id": "507f1f77bcf86cd799439011",
"contact_name": "Acme Corp",
"description": "string",
"date": "2024-01-15",
"due_date": "2024-02-15",
"subtotal": "100.00",
"discount": "0",
"total": "121.00",
"tax": "21.00",
"currency": "EUR",
"status": "pending",
"tags": [
"string"
],
"lines": [
{
"line_id": "string",
"name": "string",
"description": "string",
"price": "100.00",
"units": "1",
"discount": "0",
"tax": "21",
"taxes": [
"string"
],
"tags": [
"string"
],
"product_id": "string",
"variant_id": "string",
"service_id": "string",
"sku": "string",
"weight": "string",
"cost_price": "string",
"account": "string",
"project_id": "string",
"retention": "string",
"unit_type": "kg",
"supplied": false
}
],
"notes": "string",
"language": "es",
"currency_change": "1.00",
"accounting_date": "2024-01-15",
"approved_at": "2024-01-15T13:00:00",
"draft": false,
"custom_fields": [
{
"field": "string",
"value": "string"
}
],
"projects_summary": [
{
"project_id": "string",
"amount": "string"
}
],
"pipeline_id": "string",
"warehouse_id": "string",
"shipping": "string",
"shipping_data": "string",
"shipping_address": {
"type": "manual",
"name": "string",
"family_name": "string",
"organization": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "ES",
"email": "string",
"phone": "string",
"mobile": "string",
"contact_address_id": "string",
"full_address": "string"
},
"from": {
"id": "string",
"doc_type": "string"
}
}Success responses
200 Proforma found application/json object id string
Unique identifier of the document
document_number string | null
Sequential number assigned to the document
contact_id string | null
Identifier of the contact associated with this document
contact_name string | null
Name of the contact associated with this document
description string | null
Free-text description of the document
date string<date> | null
Issue date of the document in ISO 8601 format
due_date string<date> | null
Payment due date in ISO 8601 format
subtotal string
Sum of all line amounts before tax and discounts, as a decimal string
discount string
Total discount applied to the document, as a decimal string
total string
Final amount including taxes and discounts, as a decimal string
tax string
Total tax amount, as a decimal string
currency string
ISO 4217 currency code
status string
Current status of the document
Enum: failed completed pending partial cancelled tags[] string[]
List of tags attached to the document
lines[] object[]
Line items included in the document
line_id string | null
Unique identifier of the line item
name string
Name or title of the line item
description string
Detailed description of the line item
price string
Unit price as a numeric string
units string
Quantity of units as a numeric string
discount string
Discount percentage applied to this line as a numeric string
tax string
Primary tax percentage applied to this line as a numeric string
taxes[] string[]
List of tax identifiers applied to this line
tags[] string[]
Tags attached to this line item
product_id string | null
Identifier of the linked product, if any
variant_id string | null
Identifier of the product variant, if any
service_id string | null
Identifier of the linked service, if any
sku string | null
Stock Keeping Unit code of the product
weight string
Weight of the item in the account default unit as a numeric string
cost_price string
Cost price as a numeric string
account string | null
Accounting account code assigned to this line
project_id string | null
Identifier of the project linked to this line
retention string
Retention percentage applied to this line as a numeric string
unit_type string | null
Unit of measure for this line item (e.g. kg, units, liters)
supplied boolean
Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base and posted to account 555.
notes string | null
Internal notes visible only to your team
language string | null
ISO 639-1 language code used for the document
currency_change string
Exchange rate applied when the document currency differs from the account currency
accounting_date string<date> | null
Date used for accounting purposes, if different from the issue date
approved_at string | null
Timestamp when the document was approved
draft boolean | null
Whether the document is still a draft
custom_fields[] object[]
User-defined custom fields attached to the document
field string
Custom field identifier
value string
Value stored in the custom field
projects_summary[] object[]
Breakdown of the document subtotal by project, across all its lines
project_id string
Identifier of the project
amount string
Subtotal amount allocated to this project, as a decimal string
pipeline_id string | null
Identifier of the pipeline stage assigned to this document
warehouse_id string | null
Identifier of the warehouse associated with this document
shipping string | null
DEPRECATED, use shipping_address.type. Shipping display mode: billing, hidden or manual, or the id of an address saved on the contact.
shipping_data string | null
DEPRECATED, use shipping_address. Single-line shipping address text.
shipping_address object | null
Structured shipping address for this document. For type billing and contact the address fields come back empty because the data lives on the contact: read it with GET /api/v2/contacts/{contact_id} (bill_address for billing, or the entry of shipping_addresses whose shipping_id equals contact_address_id for contact). full_address is the address as a single line of text.
type string required
Address mode: manual (uses the address fields), billing (the billing address of the contact), hidden (no address displayed) or contact (an address saved on the contact, see contact_address_id)
Enum: billing hidden manual contact name string | null optional
Name of the shipping recipient (the given name when family_name is also sent)
family_name string | null optional
Family name of the shipping recipient
organization string | null optional
Company or organization of the shipping recipient
address_line_1 string | null optional
Primary address line
address_line_2 string | null optional
Secondary address line
city string | null optional
City or locality
postal_code string | null optional
Postal or ZIP code
province string | null optional
State, province, or region
country string | null optional
Country name
country_code string | null optional
ISO 3166-1 alpha-2 country code
email string | null optional
Contact email for shipping
phone string | null optional
Contact phone number for shipping
mobile string | null optional
Mobile number for shipping
contact_address_id string | null optional
Identifier of an address saved on the contact (shipping_id in the contact shipping_addresses). Required when type is contact
full_address string | null optional
The shipping address as a single line of text
from object | null
Source document this proforma was created from
id string
Identifier of the source document
doc_type string
Type of the source document
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Proforma not found application/json 429 Rate limit exceeded application/json