> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Envoyer un fax > Sends a PDF as a fax from one of your Allo lines. The line must be a US or Canada local number on which fax is turned on in the number settings ("Send and receive faxes"), and fax must be enabled on your account. Each page uses message credits. The request is `multipart/form-data`, not JSON. The fax is sent asynchronously: the response returns the new conversation item with `status` `PENDING`, and `page_count` is set once the fax has been sent. > [!NOTE] > > **Scope requis :** `FAX_SEND` ## Comportement Envoie un PDF par fax depuis l'une de vos lignes Allo. La requête est en `multipart/form-data` avec trois parties : `from`, `to` et `file`. ```bash theme={null} curl -X POST https://api.withallo.com/v2/api/faxes \ -H "Authorization: Api-Key YOUR_API_KEY" \ -F "from=+14155550100" \ -F "to=+14155551234" \ -F "file=@contract.pdf;type=application/pdf" ``` La réponse est `201` avec le nouvel élément de conversation : `type` `SMS`, `message_type` `FAX`, `status` `PENDING`, et le PDF dans `attachments`. Le fax part en arrière-plan. `page_count` vaut `null` dans cette réponse et est renseigné une fois le fax envoyé. Récupérez l'élément plus tard avec [Obtenir un élément de conversation](https://help.withallo.com/fr/v2/api-reference/conversations/get-item.md) pour suivre son `status`. ## Prérequis * Le fax est activé sur votre compte. * `from` est un numéro local des États-Unis ou du Canada que vous pouvez utiliser, avec **Envoyer et recevoir des fax** activé dans les paramètres du numéro, dans l'application Allo. Les numéros gratuits et les sender IDs ne peuvent pas envoyer de fax. * `file` est un PDF envoyé avec le type de contenu `application/pdf`, de 12 Mo au maximum. * Votre équipe a assez de [crédits](https://help.withallo.com/fr/billing/credits.md). Chaque page envoyée utilise des crédits de messages. Voir la [vue d'ensemble du fax](https://help.withallo.com/fr/v2/api-reference/fax/overview.md) pour savoir comment les fax apparaissent dans les conversations. ## Erreurs | Statut | Code | Quand | | - | - | - | | `400` | `MISSING_PARAMETER` | `from`, `to` ou `file` est absent | | `400` | `FAX_NOT_SUPPORTED_ON_NUMBER` | La ligne `from` ne peut pas envoyer de fax | | `400` | `FAX_NOT_ENABLED_ON_LINE` | **Envoyer et recevoir des fax** est désactivé sur la ligne `from` | | `400` | `FAX_FILE_NOT_PDF` | `file` n'est pas envoyé en `application/pdf` | | `400` | `FAX_FILE_EMPTY` | `file` est vide | | `400` | `MAX_UPLOAD_SIZE_EXCEEDED` | `file` dépasse 12 Mo | | `402` | `INSUFFICIENT_CREDITS` | Votre équipe n'a pas assez de crédits pour envoyer le fax | | `403` | `FAX_NOT_AVAILABLE` | Le fax n'est pas activé sur votre compte. Contactez le support Allo. | | `404` | `FROM_NUMBER_NOT_FOUND` | `from` n'est pas une ligne que vous pouvez utiliser | Les autres erreurs, comme un numéro `to` invalide, sont les mêmes que pour [l'envoi d'un SMS](https://help.withallo.com/fr/v2/api-reference/sms/send-sms.md). Voir [Codes d'erreur](https://help.withallo.com/fr/v2/api-reference/guides/error-codes.md). ## OpenAPI ````yaml POST /v2/api/faxes openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Fax description: >- Send a PDF as a fax from an Allo line with fax turned on. Sent and received faxes appear in conversation items. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. - name: AI Receptionist description: >- Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources. - name: Inboxes description: >- Personal inboxes: saved views of one or more lines, optionally narrowed to phone-menu options, with their own filters and notification setting. paths: /v2/api/faxes: post: tags: - Fax summary: Send fax description: >- Sends a PDF as a fax from one of your Allo lines. The line must be a US or Canada local number on which fax is turned on in the number settings ("Send and receive faxes"), and fax must be enabled on your account. Each page uses message credits. The request is `multipart/form-data`, not JSON. The fax is sent asynchronously: the response returns the new conversation item with `status` `PENDING`, and `page_count` is set once the fax has been sent. operationId: sendFax requestBody: required: true content: multipart/form-data: schema: type: object properties: from: type: string description: >- Allo line to send from, in E.164 format. Must be a line you can use with fax turned on. List your lines with `GET /v2/api/numbers`. example: '+14155550100' to: type: string description: Fax number of the recipient, in E.164 format. example: '+14155551234' file: type: string format: binary description: >- The document to fax: a PDF (`application/pdf`) of at most 12 MB. required: - from - to - file encoding: file: contentType: application/pdf responses: '201': description: Fax accepted for sending. Returns the new conversation item. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ConversationItem' example: data: id: msg-abc123 type: SMS direction: OUTBOUND allo_number: '+14155550100' contact_number: '+14155551234' contacts: [] user: id: usr-abc123 name: Alex Kim email: alex@example.com date: '2026-11-10T14:30:00' content: '' status: PENDING message_type: FAX attachments: - file_name: contract.pdf content_type: application/pdf file_size: 184320 download_url: >- https://...contract.pdf?X-Amz-Expires=1800&X-Amz-Signature=... download_expires_at: '2026-11-10T15:00:00Z' page_count: null '400': $ref: '#/components/responses/ApiValidationError' '401': $ref: '#/components/responses/ApiUnauthorized' '402': description: Not enough message credits to send the fax content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': $ref: '#/components/responses/ApiForbidden' '404': $ref: '#/components/responses/ApiNotFound' '429': $ref: '#/components/responses/ApiRateLimited' security: - FaxAuth: [] components: schemas: ConversationItem: type: object properties: id: type: string example: cll-abc123 type: type: string enum: - CALL - SMS description: >- `CALL` for a call, `SMS` for a message. Faxes are `SMS` items with `message_type` set to `FAX`. direction: type: string enum: - INBOUND - OUTBOUND allo_number: type: string example: '+14155550100' contact_number: type: string example: '+14155551234' contacts: type: array items: $ref: '#/components/schemas/Contact' user: $ref: '#/components/schemas/UserRef' date: type: string format: date-time duration: type: integer nullable: true description: >- Total call length in seconds, from when the call starts (ringing included) to when it ends. For the talk time shown in the Allo app, use `recording_duration`. result: type: string nullable: true enum: - ANSWERED - VOICEMAIL - TRANSFERRED_AI - TRANSFERRED_EXTERNAL - BLOCKED - FAILED - FAILED_EXTERNAL - RECEIVED - CLOSED description: >- Call outcome. Null for SMS items. An outbound call that reached voicemail reports `VOICEMAIL`. `FAILED_EXTERNAL` only appears on older calls. New values may be added: handle unknown values gracefully. detected_outbound_voicemail: type: boolean nullable: true description: >- Outbound calls only. `true` when the call was answered by an answering machine, `false` when a human answered, `null` when no detection ran for this call (never set on inbound calls or SMS). Note that `result` stays `ANSWERED` for these calls — the carrier considers a machine pickup an answer. voicemail_left: type: boolean nullable: true description: >- Outbound calls only. `true` when a message was actually left on the voicemail, `false` when the caller hung up without leaving one, `null` when not determined. Independent of `detected_outbound_voicemail`: either can be set without the other. recording_url: type: string nullable: true description: >- Link to the call recording. Absent when the call was not recorded, and for accounts sold under a white-label partner's brand: use `recording_download_url` there. recording_download_url: type: string nullable: true description: >- Signed link that downloads the recording with no login, valid for 48 hours. Returned only for lines of accounts created by a partner, never for a call on a HIPAA-enabled team, and only when the key's user can play the recording. For a fresh link, call `GET /v2/api/conversations/items/{id}/recording`. recording_download_expires_at: type: string format: date-time nullable: true description: When `recording_download_url` stops working. recording_duration: type: integer nullable: true description: >- Length of the call recording in seconds: the talk time, excluding ringing. This is the duration shown in the Allo app for recorded calls. `null` when the call was not recorded. summary: type: string nullable: true tags: type: array items: type: string nullable: true extracted_data: type: object nullable: true description: >- Contact details Allo's AI picked up from the call transcript, under a `contact` object: `name`, `company`, `job_title`, `website`, `address` (strings, empty when not mentioned) and `emails` (array). Null for SMS items and for calls Allo has not analyzed. properties: contact: type: object properties: name: type: string company: type: string job_title: type: string website: type: string address: type: string emails: type: array items: type: string additionalProperties: true example: contact: name: Marie Dupont company: Vibrant Events job_title: Office manager website: vibrantevents.com address: 12 rue de la Paix, Paris emails: - marie@vibrantevents.com data_collected: type: object nullable: true additionalProperties: type: string description: >- Legacy field kept for compatibility. An empty object on current calls. Null for SMS items. transcript: type: array nullable: true items: $ref: '#/components/schemas/TranscriptEntry' content: type: string nullable: true status: type: string nullable: true enum: - PENDING - SENT - DELIVERED - FAILED message_type: type: string nullable: true enum: - SMS - MMS - WHATSAPP - FAX attachments: type: array nullable: true description: >- Photos and other files sent with the message, in the order they were sent. For a fax, the faxed PDF. An empty array for a message with no files, and `null` for a call. items: $ref: '#/components/schemas/MessageAttachment' page_count: type: integer nullable: true description: >- Number of pages of a fax. `null` for calls, for messages that are not faxes, and for a fax whose page count is not known yet. example: 4 ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true Contact: type: object properties: id: type: string example: cnt-abc123 name: type: string example: Sarah Johnson company: type: object nullable: true properties: id: type: string example: com-xyz789 name: type: string example: Acme Corp deals: type: array items: type: object properties: id: type: string example: dea-def456 name: type: string example: Enterprise Plan status: type: string enum: - OPEN - WON - LOST UserRef: type: object properties: id: type: string example: usr-abc123 name: type: string example: John email: type: string example: john@acme.com TranscriptEntry: type: object properties: source: type: string enum: - USER - EXTERNAL time: type: string format: date-time text: type: string MessageAttachment: type: object properties: file_name: type: string example: IMG_0412.jpg content_type: type: string description: MIME type of the file. example: image/jpeg file_size: type: integer format: int64 nullable: true description: Size of the file in bytes. example: 245760 download_url: type: string nullable: true description: >- Signed link that downloads the file with no login, valid for 30 minutes. `null` for a message on a HIPAA-enabled team. For a fresh link, fetch the item again. download_expires_at: type: string format: date-time nullable: true description: When `download_url` stops working. responses: ApiValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiForbidden: description: API key lacks the required scope or access to the resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: FaxAuth: type: apiKey in: header name: Authorization description: 'Scope needed: `FAX_SEND`' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.