# CreateAndLinkNewFirmClientAccount

Request a new FirmClient account and create an approved linkage to it

`POST /api/v2/firmclientlinkages/createandlinkclient`

**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/CreateAndLinkNewFirmClientAccount/

## Description

This API is for use by Firms only.
            
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.
            
Calling this API creates an account with the specified product subscriptions, but without a new user for account.
Account is then linked to the Firm so they can managed their returns.
You should call this API when a customer does not have an AvaTax account and is to be managed only by the firm.
            
The created account will be created in `Active` status but there will be no user or license key associated with account.

### Security Policies

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

## 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:** `NewFirmClientAccountRequestModel`

Represents a request for a new account with Avalara for a new Firm client.

| Property | Type | Required | Description |
|---|---|---|---|
| `accountName` | string | **Yes** | The name of the account to create Example: `BizTech Company Inc.`. |
| `firstName` | string | **Yes** | First name of the primary contact person for this account Example: `Bob`. |
| `lastName` | string | **Yes** | Last name of the primary contact person for this account Example: `Example`. |
| `title` | string | No | Title of the primary contact person for this account |
| `phoneNumber` | string | No | Phone number of the primary contact person for this account |
| `email` | string | **Yes** | Email of the primary contact person for this account Example: `bob@example.org`. |
| `companyCode` | string | No | Company code to be assigned to the company created for this account.
            
If no company code is provided, this will be defaulted to "DEFAULT" company code. Example: `DEFAULT`. |
| `companyAddress` | CompanyAddress | **Yes** | Address information of the account being created. |
| `taxPayerIdNumber` | string | No | United States Taxpayer ID number, usually your Employer Identification Number if you are a business or your
Social Security Number if you are an individual.
This value is required if the address provided is inside the US. Otherwise it is optional. |
| `properties` | string[] | No | Properties of the primary contact person for this account |

## 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/createandlinkclient" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "accountName": "BizTech Company Inc.",
  "firstName": "Bob",
  "lastName": "Example",
  "email": "bob@example.org",
  "companyCode": "DEFAULT",
  "companyAddress": {
    "line": "100 Ravine Ln",
    "region": "WA",
    "country": "US",
    "postalCode": "98010"
  }
}'
```