# Received Faxes

## List Received Faxes

GET `/received_faxes` — Returns a paginated list of received faxes for your account.

Query params: `page`, `page_size`, `from_number`, `to_number`, `caller_name`, `date_start`, `date_end`, `fax_status`, `is_test`, `client`, `callback_status`.

#### cURL

```bash
export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -H "Authorization: Bearer $API_KEY" "$API_BASE/received_faxes?page=1&page_size=10&fax_status=success" | jq
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';
const res=await fetch(`${API_BASE}/received_faxes?page=1&page_size=10`,{headers:{Authorization:`Bearer ${API_KEY}`}});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE: string='https://api.medsender.com/api/v2';
const API_KEY: string='sk_test_...';
const res = await fetch(`${API_BASE}/received_faxes?page=1&page_size=10`, { headers: { Authorization: `Bearer ${API_KEY}` } });
console.log(await res.json());
```

#### Python

```python
import requests
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'
r=requests.get(f"{API_BASE}/received_faxes", headers={'Authorization':f'Bearer {API_KEY}'}, params={'page':1,'page_size':10})
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
uri = URI.parse('https://api.medsender.com/api/v2/received_faxes?page=1&page_size=10')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_test_...'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(req)}
puts res.body
```

#### PHP

```php
<?php
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/received_faxes?page=1&page_size=10',
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...'],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);
echo $res;
```

#### Java

```java
import java.net.http.*;
import java.net.URI;
public class ListReceivedFaxes {
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newHttpClient();
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/received_faxes?page=1&page_size=10"))
      .header("Authorization","Bearer sk_test_...")
      .GET()
      .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}
```

#### C#

```csharp
using System;
using System.Net.Http;
var url = "https://api.medsender.com/api/v2/received_faxes?page=1&page_size=10";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","Bearer sk_test_...");
var res = await client.GetAsync(url);
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

Response

```json
{
  "received_faxes": [
    {
      "from_number": "+15550100002",
      "to_number": "+15550100001",
      "send_token": "a3b4c5d6e7f8",
      "caller_name": "EXAMPLE CLINIC",
      "sent_at": "2025-01-15T09:15:00.000Z",
      "completed_at": "2025-01-15T09:16:00.000Z",
      "num_pages": 3,
      "is_test": false,
      "fax_status": "success",
      "error_details": null,
      "client": "client_001",
      "patient_name": "John Doe",
      "patient_dob": "1990-01-15",
      "callback_status": "success",
      "document_classification": "Referral",
      "secondary_category": null,
      "patient_first_name": "John",
      "patient_middle_name": null,
      "patient_last_name": "Doe",
      "insurance_member_id": "MEM000000001",
      "reference_number": "REF-2025-001",
      "authorization_number": null,
      "codes": [{"code": "99213"}],
      "auth_date_range_start": null,
      "auth_date_range_end": null,
      "denial_reason": null
    }
  ],
  "meta": {
    "total_count": 15,
    "total_pages": 2,
    "per_page": 10,
    "page": 1
  }
}
```

Response Fields

| Field | Description |
| --- | --- |
| send_token | Unique identifier for this fax |
| from_number | The fax number that sent this fax |
| to_number | Your Medsender fax number that received it |
| caller_name | Caller ID name from the sending fax machine |
| fax_status | Reception status: "success" or "failure" |
| sent_at | When the fax started transmitting (ISO 8601) |
| completed_at | When the fax finished receiving (ISO 8601) |
| num_pages | Number of pages received |
| is_test | Whether this was a test fax |
| error_details | Error information if fax_status is "failure" |
| callback_status | Status of webhook delivery: "success", "failure", or "pending" |
| client | Client ID if the fax number is assigned to a client |

**AI Extraction Fields** (populated when AI extraction is enabled for your account):

| Field | Description |
| --- | --- |
| document_classification | Document type: "Referral", "Lab Result", "Prior Authorization", etc. |
| patient_name | Full patient name extracted from document |
| patient_first_name | Patient first name |
| patient_middle_name | Patient middle name |
| patient_last_name | Patient last name |
| patient_dob | Patient date of birth (YYYY-MM-DD) |
| insurance_member_id | Insurance member ID |
| reference_number | Reference number from document |
| authorization_number | Prior authorization number |
| codes | Array of medical codes (CPT, ICD, etc.) |
| auth_date_range_start | Authorization start date |
| auth_date_range_end | Authorization end date |
| denial_reason | Denial reason if document is a denial |

## Get Received Fax

GET `/received_faxes/:id` — Retrieves details for a specific received fax.

The `:id` parameter is the fax's `sendToken`.

#### cURL

```bash
curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN" | jq
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';
const id='REPLACE_SEND_TOKEN';
const res=await fetch(`${API_BASE}/received_faxes/${id}`,{headers:{Authorization:`Bearer ${API_KEY}`}});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE: string='https://api.medsender.com/api/v2';
const API_KEY: string='sk_test_...';
const id: string='REPLACE_SEND_TOKEN';
const res = await fetch(`${API_BASE}/received_faxes/${id}`, { headers: { Authorization: `Bearer ${API_KEY}` } });
console.log(await res.json());
```

#### Python

```python
import requests
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'
id='REPLACE_SEND_TOKEN'
r=requests.get(f"{API_BASE}/received_faxes/{id}", headers={'Authorization':f'Bearer {API_KEY}'})
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
id = 'REPLACE_SEND_TOKEN'
uri = URI.parse("https://api.medsender.com/api/v2/received_faxes/#{id}")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer sk_test_...'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(req)}
puts res.body
```

#### PHP

```php
<?php
$id = 'REPLACE_SEND_TOKEN';
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/received_faxes/' . $id,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...'],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);
echo $res;
```

#### Java

```java
import java.net.http.*;
import java.net.URI;
public class GetReceivedFax {
  public static void main(String[] args) throws Exception {
    var id = "REPLACE_SEND_TOKEN";
    var client = HttpClient.newHttpClient();
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/received_faxes/" + id))
      .header("Authorization","Bearer sk_test_...")
      .GET()
      .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}
```

#### C#

```csharp
using System;
using System.Net.Http;
var id = "REPLACE_SEND_TOKEN";
var url = "https://api.medsender.com/api/v2/received_faxes/" + id;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","Bearer sk_test_...");
var res = await client.GetAsync(url);
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

Response

```json
{
  "from_number": "+15550100002",
  "to_number": "+15550100001",
  "send_token": "a3b4c5d6e7f8",
  "caller_name": "EXAMPLE CLINIC",
  "sent_at": "2025-01-15T09:15:00.000Z",
  "completed_at": "2025-01-15T09:16:00.000Z",
  "num_pages": 3,
  "is_test": false,
  "fax_status": "success",
  "error_details": null,
  "client": "client_001",
  "patient_name": "John Doe",
  "patient_dob": "1990-01-15",
  "callback_status": "success",
  "document_classification": "Referral",
  "secondary_category": null,
  "patient_first_name": "John",
  "patient_middle_name": null,
  "patient_last_name": "Doe",
  "insurance_member_id": "MEM000000001",
  "reference_number": "REF-2025-001",
  "authorization_number": null,
  "codes": [{"code": "99213"}],
  "auth_date_range_start": null,
  "auth_date_range_end": null,
  "denial_reason": null
}
```

## Test Receive (Sandbox)

POST `/received_faxes/test_receive` — Simulates receiving a fax for testing webhooks and integrations.

- **to_number** must be a fax number that belongs to your Medsender account.
- **from_number** can be any E.164 number (it is echoed in the callback payload and portal UI).
- Attach a small PDF or TIFF file; it will be delivered to your portal and via webhook.

#### cURL

```bash
export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."

curl -s -X POST -H "Authorization: Bearer $API_KEY" -F "file=@./sample.pdf" -F "to_number=+1YOUR_TEST_NUMBER" -F "from_number=+13125550123" "$API_BASE/received_faxes/test_receive"
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';
const fd=new FormData();
fd.append('file', new Blob([await Deno.readFile('./sample.pdf')]), 'sample.pdf');
fd.append('to_number','+1YOUR_TEST_NUMBER');
fd.append('from_number','+13125550123');
const res=await fetch(`${API_BASE}/received_faxes/test_receive`,{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`},body:fd});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE: string='https://api.medsender.com/api/v2';
const API_KEY: string='sk_test_...';
const fd = new FormData();
fd.append('file', new Blob([await (await fetch('./sample.pdf')).arrayBuffer()]), 'sample.pdf');
fd.append('to_number','+1YOUR_TEST_NUMBER');
fd.append('from_number','+13125550123');
const res = await fetch(`${API_BASE}/received_faxes/test_receive`, { method:'POST', headers:{ Authorization: `Bearer ${API_KEY}` }, body: fd });
console.log(await res.json());
```

#### Python

```python
import requests
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'
files={'file':open('./sample.pdf','rb')}
data={'to_number':'+1YOUR_TEST_NUMBER','from_number':'+13125550123'}
r=requests.post(f"{API_BASE}/received_faxes/test_receive", headers={'Authorization':f'Bearer {API_KEY}'}, files=files, data=data)
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
uri = URI.parse('https://api.medsender.com/api/v2/received_faxes/test_receive')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer sk_test_...'
form = [ ['file', File.open('sample.pdf')], ['to_number','+1YOUR_TEST_NUMBER'], ['from_number','+13125550123'] ]
request.set_form(form, 'multipart/form-data')
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(request)}
puts res.body
```

#### PHP

```php
<?php
$ch = curl_init();
$post = [
  'file' => new CURLFile('sample.pdf', 'application/pdf', 'sample.pdf'),
  'to_number' => '+1YOUR_TEST_NUMBER',
  'from_number' => '+13125550123'
];
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/received_faxes/test_receive',
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...'],
  CURLOPT_POSTFIELDS => $post,
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);
echo $res;
```

#### Java

```java
import java.net.http.*;
import java.net.URI;
public class TestReceive {
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newHttpClient();
    // Simplified example: build multipart form data manually
    var boundary = "--------------------------MedsenderBoundary";
    var body = "--" + boundary + "\r\n" +
      "Content-Disposition: form-data; name=\"to_number\"\r\n\r\n+1YOUR_TEST_NUMBER\r\n" +
      "--" + boundary + "\r\n" +
      "Content-Disposition: form-data; name=\"from_number\"\r\n\r\n+13125550123\r\n" +
      "--" + boundary + "--\r\n";
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/received_faxes/test_receive"))
      .header("Authorization","Bearer sk_test_...")
      .header("Content-Type","multipart/form-data; boundary=" + boundary)
      .POST(HttpRequest.BodyPublishers.ofString(body))
      .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}
```

#### C#

```csharp
using System;
using System.Net.Http;
using System.Threading.Tasks;
var url = "https://api.medsender.com/api/v2/received_faxes/test_receive";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","Bearer sk_test_...");
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(System.IO.File.ReadAllBytes("sample.pdf")), "file", "sample.pdf");
form.Add(new StringContent("+1YOUR_TEST_NUMBER"), "to_number");
form.Add(new StringContent("+13125550123"), "from_number");
var res = await client.PostAsync(url, form);
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

Response

```json
{
  "message": "Sent test fax to your fax number. Sending callback now..."
}
```

## Forward a Received Fax

POST `/received_faxes/:id/forward_as_fax` — Forwards a received fax to another fax number.

The `:id` parameter is the fax's `sendToken`.

#### cURL

```bash
curl -s -X POST -H "Authorization: Bearer sk_test_..." -F "to_number=+13125550123" "https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN/forward_as_fax" | jq
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';
const id='REPLACE_SEND_TOKEN';
const body=new URLSearchParams({ to_number: '+13125550123' });
const res=await fetch(`${API_BASE}/received_faxes/${id}`+"/forward_as_fax",{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`,'Content-Type':'application/x-www-form-urlencoded'},body});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE: string='https://api.medsender.com/api/v2';
const API_KEY: string='sk_test_...';
const id: string='REPLACE_SEND_TOKEN';
const body = new URLSearchParams({ to_number: '+13125550123' });
const res = await fetch(`${API_BASE}/received_faxes/${id}`+"/forward_as_fax", { method:'POST', headers:{ Authorization: `Bearer ${API_KEY}`, 'Content-Type':'application/x-www-form-urlencoded' }, body });
console.log(await res.json());
```

#### Python

```python
import requests
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'
id='REPLACE_SEND_TOKEN'
data={'to_number':'+13125550123'}
r=requests.post(f"{API_BASE}/received_faxes/{id}/forward_as_fax", headers={'Authorization':f'Bearer {API_KEY}','Content-Type':'application/x-www-form-urlencoded'}, data=data)
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
uri = URI.parse('https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN/forward_as_fax')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer sk_test_...'
request.set_form({ 'to_number' => '+13125550123' }, 'application/x-www-form-urlencoded')
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(request)}
puts res.body
```

#### PHP

```php
<?php
$ch = curl_init();
$post = [ 'to_number' => '+13125550123' ];
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN/forward_as_fax',
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...'],
  CURLOPT_POSTFIELDS => $post,
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);
echo $res;
```

#### Java

```java
import java.net.http.*;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
public class ForwardFax {
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newHttpClient();
    var body = "to_number=" + URLEncoder.encode("+13125550123", StandardCharsets.UTF_8);
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN/forward_as_fax"))
      .header("Authorization", "Bearer sk_test_...")
      .header("Content-Type", "application/x-www-form-urlencoded")
      .POST(HttpRequest.BodyPublishers.ofString(body))
      .build();
    var res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}
```

#### C#

```csharp
using System;
using System.Net.Http;
using System.Threading.Tasks;
var url = "https://api.medsender.com/api/v2/received_faxes/REPLACE_SEND_TOKEN/forward_as_fax";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_test_...");
var form = new FormUrlEncodedContent(new [] { new KeyValuePair<string,string>("to_number", "+13125550123") });
var res = await client.PostAsync(url, form);
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

Response

```json
{
  "message": "Record has been sent, we will send a callback upon completion.",
  "fax_id": "f5cfd99304f9"
}
```

## Automatic AI Extraction

By default, when you receive a fax, your callback fires immediately with the fax details.

To automatically extract patient information, document classification, and medical codes from every incoming fax, **contact us at [support@medsender.com](mailto:support@medsender.com)** to enable this feature for your account.

**When enabled:**

- Incoming faxes are processed by AI before your callback fires
- Processing may take up to a few minutes depending on document complexity
- Your callback payload includes these additional fields when populated:

- `documentClassification`, `secondaryCategory`
- `patientName`, `patientFirstName`, `patientMiddleName`, `patientLastName`
- `patientDob`, `insuranceMemberId`
- `referenceNumber`, `authorizationNumber`, `codes`
- `authDateRangeStart`, `authDateRangeEnd`, `denialReason`

You can always run AI manually on any document using the [AI Documents](/docs/ai-documents) endpoint.