W-9 requests
Create or update a W-9 request
Save a request to collect a W-9 from a recipient.
/api/v1/w9/requests/upsert- Authentication
- OAuth 2.0 access token
- Required scopes
w9.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Select an authorized issuer; restricted connections require a filer-backed issuer. Send the current version when updating. Creating a request requires purchased W-9 capacity. Use dispatch to send its collection link.
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/requests/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
13 fieldsemailRequiredstring (email)
Minimum characters: 3. Maximum characters: 254.
account_refOptionalstring | null
Maximum characters: 80.
business_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.
person_first_nmOptionalstring | null
Maximum characters: 160.
person_last_nmOptionalstring | null
Maximum characters: 160.
person_middle_nmOptionalstring | null
Maximum characters: 160.
person_suffix_nmOptionalstring | null
Maximum characters: 160.
recipient_nameOptionalstring | null
Maximum characters: 160.
request_idOptionalstring (uuid) | null
ID of 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/requests/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
35 fieldsaccount_refMay be omittedstring | null
Maximum characters: 512.
business_nameMay be omittedstring | null
Maximum characters: 512.
canceled_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
converted_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
converted_filer_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
converted_recipient_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
created_atAlways returnedstring (date-time)
Type: string (date-time).
dispatched_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
emailAlways returnedstring | null
Maximum characters: 512.
entity_type_cdMay be omittedstring | null
Maximum characters: 512.
issuer_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
issuer_snapshotMay be omittedobject | null
Type: object | null.
{
"data": {
"account_ref": "string | null",
"business_name": "string | null",
"canceled_at": "string (date-time) | null",
"converted_at": "string (date-time) | null",
"converted_filer_id": "string (uuid) | null",
"converted_recipient_id": "string (uuid) | null",
"created_at": "string (date-time)",
"dispatched_at": "string (date-time) | null",
"email": "string | null",
"entity_type_cd": "string | null",
"issuer_id": "string (uuid) | null",
"issuer_snapshot": "object | null",
"opened_at": "string (date-time) | null",
"person_first_nm": "string | null",
"person_last_nm": "string | null",
"person_middle_nm": "string | null",
"person_suffix_nm": "string | null",
"prior_request_id": "string (uuid) | null",
"purpose": "string | null",
"recipient_name": "string | null",
"reconfirmation_apply_status": "string | null",
"reconfirmation_data": "object | null",
"reconfirmation_review_reason": "string | null",
"request_id": "string (uuid)",
"source_recipient_version": "integer | null",
"status": "string | null",
"submitted_at": "string (date-time) | null",
"submitted_data": "object | null",
"target_filer_id": "string (uuid) | null",
"target_recipient_id": "string (uuid) | null",
"tax_classification": "string | null",
"tin_last4": "string | null",
"tin_type": "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.
- 402
w9_capacity_required - Creating W-9 requests requires purchased capacity; sending them requires a paid request. Review W-9 capacity in E-File Magic before retrying.