W-9 requests
Create or update a W-9 issuer
Save the sender details used on W-9 requests.
/api/v1/w9/issuers/upsert- Authentication
- OAuth 2.0 access token
- Required scopes
w9.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Send the current version when updating. A restricted connection must use a filer-backed issuer and an allowed filer. Tax IDs are not echoed.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
curl --request POST 'https://api.efilemagic.com/api/v1/w9/issuers/upsert' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonReplace placeholders with your own values. Use the API resource origin provided for your environment.
Create request.json using the documented fields. Field descriptions are not sample values.
Request fields
24 fieldsdisplay_nameRequiredstring
Minimum characters: 1. Maximum characters: 160.
legal_nameRequiredstring
Minimum characters: 1. Maximum characters: 160.
address_line1Optionalstring | null
Maximum characters: 160.
address_line2Optionalstring | null
Maximum characters: 160.
cityOptionalstring | null
Maximum characters: 80.
contact_emailOptionalstring (email) | null
Maximum characters: 254.
contact_nameOptionalstring | null
Maximum characters: 160.
countryOptionalstring | null
Maximum characters: 80.
dba_nameOptionalstring | null
Maximum characters: 160.
entity_type_cdOptionalstring | null
Allowed values: "B", "I".
expected_versionOptionalinteger | null
Version from the latest read of the record. A changed version requires review before updating. Minimum: 1.
issuer_idOptionalstring (uuid) | null
ID of the sender issuing the W-9 request.
Headers (3)
AuthorizationRequired- OAuth RS256 access token issued for the EFM API resource. Interactive EFM session tokens are rejected.
Idempotency-KeyRequired- Opaque caller-generated key bound to resolved tenant, connection, and actor scope.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request POST 'https://api.efilemagic.com/api/v1/w9/issuers/upsert' \
--header 'Authorization: Bearer <access-token>' \
--header 'Idempotency-Key: <unique-operation-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonReplace placeholders with your own values. Use the API resource origin provided for your environment.
Create request.json using the documented fields. Field descriptions are not sample values.
Retrying a request? Keep the same idempotency key and body after an uncertain result. A different key can repeat the action.
On success, data contains the fields below. meta includes api_version and request_id. Keep request_id when reporting a problem.
Response fields
28 fieldsaddress_line1May be omittedstring | null
Maximum characters: 512.
address_line2May be omittedstring | null
Maximum characters: 512.
arch_bucketAlways returnedstring | null
Maximum characters: 512.
cityMay be omittedstring | null
Maximum characters: 512.
contact_emailMay be omittedstring | null
Maximum characters: 512.
contact_nameMay be omittedstring | null
Maximum characters: 512.
countryMay be omittedstring | null
Maximum characters: 512.
created_atAlways returnedstring (date-time)
Type: string (date-time).
dba_nameMay be omittedstring | null
Maximum characters: 512.
display_nameAlways returnedstring | null
Maximum characters: 512.
entity_type_cdMay be omittedstring | null
Maximum characters: 512.
is_archivedAlways returnedboolean
Type: boolean.
{
"data": {
"address_line1": "string | null",
"address_line2": "string | null",
"arch_bucket": "string | null",
"city": "string | null",
"contact_email": "string | null",
"contact_name": "string | null",
"country": "string | null",
"created_at": "string (date-time)",
"dba_name": "string | null",
"display_name": "string | null",
"entity_type_cd": "string | null",
"is_archived": "boolean",
"issuer_id": "string (uuid)",
"legal_name": "string | null",
"name1": "string | null",
"name2": "string | null",
"person_first_nm": "string | null",
"person_last_nm": "string | null",
"person_middle_nm": "string | null",
"person_suffix_nm": "string | null",
"phone": "string | null",
"postal_code": "string | null",
"source_id": "string (uuid) | null",
"source_type": "string | null",
"state": "string | null",
"status": "string | null",
"updated_at": "string (date-time)",
"version": "integer"
},
"meta": {
"api_version": "v1",
"request_id": "string"
}
}Successful response structure. This outline shows field types, not a response to copy. Expand Response fields for nested properties and optional values.
Errors to handle
Errors use {error: {code, message}, meta}. Check the code and message before retrying. Authentication, validation and availability errors can occur before the operation runs.
- 400
invalid_request - Check required fields, selectors and supported values.
- 401
invalid_token - Obtain a valid OAuth token for this resource. Check its expiry and current authorization.
- 403
insufficient_scope - Request the listed scopes through the application's authorization flow.
- 403
forbidden - Check the connection's permissions and allowed filers. More scopes alone may not grant access.
- 404
not_found - Check the resource ID and its owning filer. Batch reads report missing IDs as documented.
- 409
conflict - Read the current state and resolve the conflict. Do not change the body under an existing idempotency key.
- 412
precondition_failed - Read the current version or preview again; a required precondition has changed.
- 422
validation_failed - Correct the reported validation issues before retrying.
- 429
rate_limited - Wait for Retry-After before retrying. Avoid concurrent retries.
- 500
internal_error - Retain request_id and retry an uncertain result with the same body and idempotency key.
- 503
service_unavailable - Retry with bounded backoff, preserving the body and idempotency key.