W-9 requests
Upload a W-9 request list
Create a W-9 import and get upload instructions for its spreadsheet.
/api/v1/w9/imports/create_upload- Authentication
- OAuth 2.0 access token
- Required scopes
w9.write- Idempotency key
- Required
- Rate-limit cost
- 5 units
How to use this endpoint
Send every returned upload header unchanged. Temporary source files are eligible for deletion after two days. Retrying the same key and body can renew the upload URL for the same pending submission. After upload, inspect the file and start the import.
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/imports/create_upload' \
--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
8 fieldscontent_typeRequiredstring
Media type of the source file. Minimum characters: 1. Maximum characters: 128.
file_nameRequiredstring
Name of the source file being uploaded. Minimum characters: 1. Maximum characters: 180.
issuer_idRequiredstring (uuid)
ID of the sender issuing the W-9 request.
size_bytesRequiredinteger
Size of the source file in bytes. Minimum: 1. Maximum: 26214400.
dispatch_immediatelyOptionalboolean
Whether to dispatch created W-9 requests as part of this workflow. Default: false.
notify_emailOptionalstring (email) | null
Maximum characters: 254.
rows_per_chunkOptionalinteger | null
Minimum: 1. Maximum: 1000.
sha256Optionalstring | null
SHA-256 digest of the source file. Pattern: ^[a-f0-9]{64}$
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, actor, exact route, and request. Capability retries revalidate the durable target and mint a fresh URL.
DPoPConditional / optional- Required when the application, connection, or credential is proof-of-possession bound.
curl --request POST 'https://api.efilemagic.com/api/v1/w9/imports/create_upload' \
--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
4 fieldssubmissionAlways returnedobject
Unknown fields are rejected.
Nested fields (20)
content_typeMay be omittedstring | null
Type: string | null.
created_atAlways returnedstring (date-time)
Type: string (date-time).
created_byAlways returnedobject
Type: object.
created_by_user_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
dispatch_requestedAlways returnedboolean
Type: boolean.
dispatched_countAlways returnedinteger
Minimum: 0.
file_nameAlways returnedstring
Type: string.
issuer_idMay be omittedstring (uuid) | null
Type: string (uuid) | null.
notify_emailMay be omittedstring (email) | null
Type: string (email) | null.
request_count_createdAlways returnedinteger
Minimum: 0.
row_count_processedAlways returnedinteger
Minimum: 0.
row_count_totalAlways returnedinteger
Minimum: 0.
rows_per_chunkAlways returnedinteger
Minimum: 1.
size_bytesMay be omittedinteger | null
Minimum: 0.
skipped_countAlways returnedinteger
Minimum: 0.
source_stage_completedAlways returnedboolean
Type: boolean.
statusAlways returnedstring
Type: string.
submission_idAlways returnedstring (uuid)
Type: string (uuid).
updated_atAlways returnedstring (date-time)
Type: string (date-time).
versionAlways returnedinteger
Minimum: 1.
upload_headersAlways returnedobject
Additional values: string.
upload_methodAlways returned"PUT"
Value: "PUT".
upload_urlAlways returnedstring (uri)
Type: string (uri).
{
"data": {
"submission": "object",
"upload_headers": "object",
"upload_method": "\"PUT\"",
"upload_url": "string (uri)"
},
"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.