# Legacy API (v2)

The legacy v2 API lets existing integrations send and receive faxes, manage fax numbers, send secure email links, create clients, and run AI on documents.

These examples use `/api/v2` and developer-owned fax resources. For organization-linked web fax workflows, use the main [Sent Faxes](/docs/sent-faxes) and [Received Faxes](/docs/received-faxes) documentation. Changing the API URL alone does not enroll an account or migrate its history.

## Quickstart: Send your first fax

Use a test key (`sk_test_…`) and a small PDF. This posts to the fax API and returns a token to check status.

#### cURL

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

# Provision a test fax number (area code 415 as example)
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fax_number":{"area_code":"415"}}' \
  "$API_BASE/fax_numbers" | jq

# Send a fax (replace numbers and attach sample.pdf)
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -F "file=@./sample.pdf" \
  -F "from_number=+14155550100" \
  -F "to_number=+13125550123" \
  "$API_BASE/sent_faxes"
```

#### Node

```javascript
const API_BASE='https://api.medsender.com/api/v2';
const API_KEY='sk_test_...';

// Provision number
await fetch(`${API_BASE}/fax_numbers`,{
  method:'POST',headers:{Authorization:`Bearer ${API_KEY}`,'Content-Type':'application/json'},
  body:JSON.stringify({fax_number:{area_code:'415'}})
});

// Send fax
const fd=new FormData();
fd.append('file', new Blob([await Deno.readFile('./sample.pdf')]), 'sample.pdf');
fd.append('from_number','+14155550100');
fd.append('to_number','+13125550123');
const res=await fetch(`${API_BASE}/sent_faxes`,{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`},body:fd});
console.log(await res.json());
```

#### TypeScript

```typescript
const API_BASE = 'https://api.medsender.com/api/v2';
const API_KEY: string = 'sk_test_...';

// Provision number
await fetch(`${API_BASE}/fax_numbers`,{
  method:'POST',headers:{Authorization:`Bearer ${API_KEY}`,'Content-Type':'application/json'},
  body:JSON.stringify({fax_number:{area_code:'415'}})
});

// Send fax
const fd = new FormData();
fd.append('file', new Blob([await (await fetch('./sample.pdf')).arrayBuffer()]), 'sample.pdf');
fd.append('from_number','+14155550100');
fd.append('to_number','+13125550123');
const res = await fetch(`${API_BASE}/sent_faxes`,{method:'POST',headers:{Authorization:`Bearer ${API_KEY}`},body:fd});
console.log(await res.json());
```

#### Python

```python
import requests, json
API_BASE='https://api.medsender.com/api/v2'
API_KEY='sk_test_...'

# Provision number
r=requests.post(f"{API_BASE}/fax_numbers", headers={'Authorization':f'Bearer {API_KEY}','Content-Type':'application/json'}, data=json.dumps({'fax_number':{'area_code':'415'}}))
print(r.json())

# Send fax
files={'file':open('./sample.pdf','rb')}
data={'from_number':'+14155550100','to_number':'+13125550123'}
r=requests.post(f"{API_BASE}/sent_faxes", headers={'Authorization':f'Bearer {API_KEY}'}, files=files, data=data)
print(r.json())
```

#### Ruby

```ruby
require 'net/http'
require 'uri'
# Provision number
uri = URI.parse('https://api.medsender.com/api/v2/fax_numbers')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer sk_test_...'
req['Content-Type'] = 'application/json'
req.body = '{"fax_number":{"area_code":"415"}}'
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true){|http| http.request(req)}

# Send fax
uri2 = URI.parse('https://api.medsender.com/api/v2/sent_faxes')
req2 = Net::HTTP::Post.new(uri2)
req2['Authorization'] = 'Bearer sk_test_...'
form = [['file', File.open('sample.pdf')], ['from_number','+14155550100'], ['to_number','+13125550123']]
req2.set_form(form, 'multipart/form-data')
res = Net::HTTP.start(uri2.hostname, uri2.port, use_ssl: true){|http| http.request(req2)}
puts res.body
```

#### PHP

```php
<?php
// Provision number
$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/fax_numbers',
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_test_...', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['fax_number' => ['area_code' => '415']]),
  CURLOPT_RETURNTRANSFER => true
]);
curl_exec($ch);

// Send fax
$post = [
  'file' => new CURLFile('sample.pdf', 'application/pdf', 'sample.pdf'),
  'from_number' => '+14155550100',
  'to_number' => '+13125550123'
];
curl_setopt_array($ch, [
  CURLOPT_URL => 'https://api.medsender.com/api/v2/sent_faxes',
  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 Quickstart {
  public static void main(String[] args) throws Exception {
    var client = HttpClient.newHttpClient();
    // Provision number (JSON)
    var pbody = "{\"fax_number\":{\"area_code\":\"415\"}}";
    var preq = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/fax_numbers"))
      .header("Authorization","Bearer sk_test_...")
      .header("Content-Type","application/json")
      .POST(HttpRequest.BodyPublishers.ofString(pbody))
      .build();
    client.send(preq, HttpResponse.BodyHandlers.ofString());
    // Send fax (simplified placeholder)
    var req = HttpRequest.newBuilder()
      .uri(URI.create("https://api.medsender.com/api/v2/sent_faxes"))
      .header("Authorization","Bearer sk_test_...")
      .POST(HttpRequest.BodyPublishers.ofString(""))
      .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;
// Provision number
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization","Bearer sk_test_...");
var json = "{\"fax_number\":{\"area_code\":\"415\"}}";
await client.PostAsync("https://api.medsender.com/api/v2/fax_numbers", new StringContent(json, System.Text.Encoding.UTF8, "application/json"));
// Send fax (simplified placeholder)
var res = await client.PostAsync("https://api.medsender.com/api/v2/sent_faxes", new StringContent(""));
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

### Endpoints (Customer)

- Sent Faxes: `GET /sent_faxes`, `GET /sent_faxes/:send_token`, `POST /sent_faxes`
- Received Faxes: `GET /received_faxes`, `GET /received_faxes/:send_token`, `POST /received_faxes/test_receive`, `POST /received_faxes/:send_token/forward_as_fax`
- Fax Numbers: `GET /fax_numbers`, `GET /fax_numbers/:slug`, `POST /fax_numbers`, `PATCH /fax_numbers/:slug`
- Clients: `GET /clients`, `GET /clients/:client_id`, `POST /clients`, `PATCH /clients/:client_id`
- Secure Links: `POST /emails`, `GET /emails/:email_id`
- AI Documents: `GET /ai_documents`, `GET /ai_documents/:ai_token`, `POST /ai_documents`

All calls use `Authorization: Bearer sk_*` with your API key. Test keys start with `sk_test_`.

### Response Examples

Create (Send Fax)

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

List (Fax Numbers)

```json
{
  "faxNumbers": [{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "number": "+15550100001",
    "callbackUrl": null,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "client": null,
    "uri": "https://api.medsender.com/api/v2/fax_numbers/f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }]
}
```