W-9 requests
Request W-9 reconfirmation
Create or update a reconfirmation workflow for an existing recipient.
/api/v1/w9/reconfirmations/upsert- Authentication
- OAuth 2.0 access token
- Required scopes
w9.writerecipients.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Both W-9 and recipient write permissions are required. Current authorization and versions are checked; creating a W-9 request requires purchased capacity.
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/reconfirmations/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
4 fieldsexpected_recipient_versionRequiredinteger
Recipient version from the latest read, used to detect a conflicting update. Minimum: 1.
filer_idRequiredstring (uuid)
ID of the filer that owns this operation's records.
recipient_idRequiredstring (uuid)
ID of the recipient within the selected filer.
send_immediatelyOptionalboolean
Whether to send the W-9 request as part of this operation. Default: false.
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/reconfirmations/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
2 fieldslinkAlways returnedobject
Type: object.
Nested fields (5)
created_atAlways returnedstring (date-time)
Type: string (date-time).
filer_idAlways returnedstring (uuid)
Type: string (uuid).
recipient_idAlways returnedstring (uuid)
Type: string (uuid).
updated_atAlways returnedstring (date-time)
Type: string (date-time).
versionAlways returnedinteger
Minimum: 1.
requestAlways returnedobject
Unknown fields are rejected.
Nested fields (35)
account_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.
opened_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
person_first_nmMay be omittedstring | null
Maximum characters: 512.
person_last_nmMay be omittedstring | null
Maximum characters: 512.
person_middle_nmMay be omittedstring | null
Maximum characters: 512.
person_suffix_nmMay be omittedstring | null
Maximum characters: 512.
prior_request_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
purposeAlways returnedstring | null
Maximum characters: 512.
recipient_nameMay be omittedstring | null
Maximum characters: 512.
reconfirmation_apply_statusMay be omittedstring | null
Maximum characters: 512.
reconfirmation_dataMay be omittedobject | null
Tax identifier is masked according to route scope.
reconfirmation_review_reasonMay be omittedstring | null
Maximum characters: 512.
request_idAlways returnedstring (uuid)
Type: string (uuid).
source_recipient_versionMay be omittedinteger | null
Minimum: 1.
statusAlways returnedstring | null
Maximum characters: 512.
submitted_atMay be omittedstring (date-time) | null
Type: string (date-time) | null.
submitted_dataMay be omittedobject | null
Tax identifier is masked according to route scope.
target_filer_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
target_recipient_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
tax_classificationMay be omittedstring | null
Maximum characters: 512.
tin_last4May be omittedstring | null
Maximum characters: 512.
tin_typeMay be omittedstring | null
Maximum characters: 512.
updated_atAlways returnedstring (date-time)
Type: string (date-time).
versionAlways returnedinteger
Minimum: 1.
{
"data": {
"link": "object",
"request": "object"
},
"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.