# InsertFirmClientLinkage

Insert a full FirmClientLinkage record

`POST /api/v2/firmclientlinkages/insert`

**API:** AvaTax API
**Tag:** FirmClientLinkages
**API Version:** v2
**Base URL:** https://sandbox-rest.avatax.com/
**Content-Type:** `application/json`
**Accepts:** `application/json`
**Authentication:** API Key (`Authorization` in header) or OAuth 2.0 or Basic (username + license key)

Source: https://developer.avalara.com/products/avatax/api/methods/FirmClientLinkages/InsertFirmClientLinkage/

## Description

Avalara allows firms to manage returns for clients without the clients needing to use AvaTax service.
Firms can create accounts of FirmClient for customers they are managing using this API.

### Security Policies

* This API requires one of the following user roles: BatchServiceAdmin, FirmAdmin, Registrar, SiteAdmin, SSTAdmin, SystemAdmin, TechnicalSupportAdmin, TechnicalSupportUser.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/) . |

## Request Body

**Schema:** `FirmClientLinkageModel`

Account Linkage output model

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of firm-client linkage. Example: `123456`. |
| `firmAccountId` | integer | No | Firm Account to be linked with the firm Example: `23982571`. |
| `firmAccountName` | string | No | FIrm Account name Example: `Firm Account`. |
| `clientAccountId` | integer | No | Client Account to be linked with the firm Example: `24958289`. |
| `clientAccountName` | string | No | Client Account name Example: `Client Account`. |
| `createdDate` | string | No | Created date of the linkage Example: `2026-07-02T04:05:12.055623+00:00`. |
| `createdUserId` | integer | No | User who created the linkage Example: `213`. |
| `modifiedDate` | string | No | Modified date of the linkage Example: `2026-07-02T04:05:12.0556591+00:00`. |
| `modifiedUserId` | integer | No | User who modified the linkage Example: `213`. |
| `status` | string | No | The status of the account linkage. The following are the available statuses
* Requested - When a linkage is requested
* Approved - When the linkage is approved
* Rejected - When the linkage is rejected
* Revoked - When the linkage is revoked. Values: `Requested`, `Approved`, `Rejected`, `Revoked`. Example: `Requested`. |
| `isDeleted` | boolean | No | This is set to 1 if the linkage is deleted. Example: `false`. |
| `firmContactName` | string | No | Name of the firm's point of contact person for the client |
| `firmContactEmail` | string | No | Email of the firm's point of contact person for the client |

## Responses

| Status | Description | Schema |
|---|---|---|
| 201 | Created | `FirmClientLinkageOutputModel` |
| 400 | Bad Request |  |
| 401 | Unauthorized |  |

### 201 Response: `FirmClientLinkageOutputModel`

Account Linkage output model

| Property | Type | Required | Description |
|---|---|---|---|
| `id` | integer | No | The unique ID number of firm-client linkage. Example: `123456`. |
| `firmAccountId` | integer | No | Firm Account to be linked with the firm Example: `23982571`. |
| `firmAccountName` | string | No | FIrm Account name Example: `Firm Account`. |
| `clientAccountId` | integer | No | Client Account to be linked with the firm Example: `24958289`. |
| `clientAccountName` | string | No | Client Account name Example: `Client Account`. |
| `createdDate` | string | No | Created date of the linkage Example: `2026-07-02T04:05:11.9956045+00:00`. |
| `createdUserId` | integer | No | User who created the linkage Example: `213`. |
| `modifiedDate` | string | No | Modified date of the linkage Example: `2026-07-02T04:05:11.9956406+00:00`. |
| `modifiedUserId` | integer | No | User who modified the linkage Example: `213`. |
| `status` | string | No | The status of the account linkage. The following are the available statuses
* Requested - When a linkage is requested
* Approved - When the linkage is approved
* Rejected - When the linkage is rejected
* Revoked - When the linkage is revoked. Values: `Requested`, `Approved`, `Rejected`, `Revoked`. Example: `Requested`. |
| `isDeleted` | boolean | No | This is set to 1 if the linkage is deleted. Example: `false`. |
| `firmContactName` | string | No | Name of the firm's point of contact person for the client |
| `firmContactEmail` | string | No | Email of the firm's point of contact person for the client |

## Example Request

```bash
curl -X POST "https://sandbox-rest.avatax.com/api/v2/firmclientlinkages/insert" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "id": 123456,
  "firmAccountId": 23982571,
  "firmAccountName": "Firm Account",
  "clientAccountId": 24958289,
  "clientAccountName": "Client Account",
  "createdDate": "2026-07-02T04:05:12.055623+00:00",
  "createdUserId": 213,
  "modifiedDate": "2026-07-02T04:05:12.0556591+00:00",
  "modifiedUserId": 213,
  "status": "Requested",
  "isDeleted": false
}'
```