For the complete documentation index, see llms.txt
For the complete documentation index, see llms.txt
tw
Help center
How to Configure and Manage Tax Profile Outreach Policies Using API
# Tax Profile Outreach Policy: Setup and API Management Guide
Tax profile outreach enables you to help your customers update their tax profiles and complete necessary tax forms (such as W-9 or W-8) via customizable branded messages. To implement and manage this, you need to follow a series of setup steps and use the corresponding API endpoints to create, update, and retrieve outreach policies.
## Setup Steps
Before creating a tax profile outreach policy, complete these essential setup steps:
1. **Configure Email Domains and Web Domains:** Ensure your email and web domains are correctly configured to support branded outreach communications.
2. **Configure White-Label Outreach:** Set up your white-label outreach themes following the "White-Label Outreach" guidelines available at [White-Label Outreach](https://www.unit.co/docs/white-label-uis/white-label-outreach/).
## Creating a Tax Profile Outreach Policy
Use the `POST` endpoint below to create a new outreach policy once setup is complete.
- Endpoint: `POST https://api.s.unit.sh/tax-profile-outreach-policies`
- Required Scope: `tax-write`
- Timeout: 5 seconds
### Request Attributes
| Field | Type | Required/Optional | Description |
|----------------|--------|-------------------|--------------------------------------------------------------|
| supportUrl | string | Optional | Client support contact URL (must be a valid https URL). |
| supportEmail | string | Optional | Client support email address. |
| idempotencyKey | string | Optional | Idempotency key for safe retry of requests. |
> At least one support contact attribute (`supportUrl` or `supportEmail`) is required. Both can be provided, and both will be displayed.
### Relationships
| Field | Type | Description |
|----------------------|--------------------|--------------------------------------------|
| whiteLabelTheme | JSON:API Relationship | The white-label theme to use for branding. |
| emailOutreachSettings| JSON:API Relationship | Email outreach settings to use for the policy. |
### Example Creation Request (cURL)
```bash
curl -X POST 'https://api.s.unit.sh/tax-profile-outreach-policies' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "createTaxProfileOutreachPolicyRequest",
"attributes": {
"supportUrl": "https://thisIsMyDomain.unit.co",
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
},
"relationships": {
"emailOutreachSettings": {
"data": {
"type": "emailOutreachSettings",
"id": "10001"
}
},
"whiteLabelTheme": {
"data": {
"type": "whiteLabelTheme",
"id": "10005"
}
}
}
}
}'
```
### Successful Creation Response
On success, you'll receive a `201 Created` status with the created `TaxProfileOutreachPolicy` resource, including timestamps and related entities.
## Updating an Outreach Policy
Use the `PATCH` endpoint to update an existing outreach policy.
- Endpoint: `PATCH https://api.s.unit.sh/tax-profile-outreach-policies/:policyId`
- Required Scope: `tax-write`
- Timeout: 5 seconds
### Updatable Attributes
| Field | Type | Description |
|--------------------|--------|----------------------------------------------|
| supportUrl | string | Optional: Update support contact URL. |
| supportEmail | string | Optional: Update support email address. |
### Updatable Relationships
| Field | Type | Description |
|------------------|--------|----------------------------------------|
| emailOutreachSettings | string | Optional: ID of email outreach settings. |
| whiteLabelTheme | string | Optional: ID of white-label theme. |
### Example Update Request
```bash
curl -X PATCH 'https://api.s.unit.sh/tax-profile-outreach-policies/:policyId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
"data": {
"type": "patchTaxProfileOutreachPolicyRequest",
"attributes": {
"idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389999",
"supportUrl": "https://thisIsMyDomain2.unit.co"
},
"relationships": {
"whiteLabelTheme": {
"data": {
"type": "whiteLabelTheme",
"id": "10009"
}
}
}
}
}'
```
### Successful Update Response
A `200 OK` status with the updated policy resource will be returned, showing new attributes and relationships.
## Retrieving an Outreach Policy by ID
Use the `GET` method to retrieve an existing tax profile outreach policy by its ID.
- Endpoint: `GET https://api.s.unit.sh/tax-profile-outreach-policies/:policyId`
- Required Scope: `tax`
- Timeout: 5 seconds
### Example Retrieval Request
```bash
curl -X GET 'https://api.s.unit.sh/tax-profile-outreach-policies/1' \
-H "Authorization: Bearer ${TOKEN}"
```
### Successful Retrieval Response
The API will respond with `200 OK` and the requested policy data.
---
By following these steps and using the API as described, you can effectively manage your organization's tax profile outreach policies with customized branded messaging to ensure that your clients complete their necessary tax forms.
