Skip to main content
POST
/
v1
/
extractions
Create extraction
curl --request POST \
  --url https://api.taxo.co/v1/extractions \
  --header 'Content-Type: application/json' \
  --data '
{
  "subject": {
    "identifier": "<string>",
    "name": "<string>"
  },
  "credentials": {
    "type": "<string>",
    "password": "<string>",
    "privateKey": "<string>",
    "certificate": "<string>"
  },
  "options": {
    "informationType": "<string>",
    "period": {
      "from": "<string>",
      "to": "<string>"
    },
    "direction": "<string>"
  },
  "filters": {
    "emitters": [
      {}
    ],
    "receivers": [
      {}
    ],
    "minAmount": 123,
    "maxAmount": 123
  }
}
'
{
  "error": {
    "code": "INVALID_RFC",
    "message": "The provided RFC does not have a valid format",
    "details": {
      "field": "subject.identifier",
      "provided": "ABC01010",
      "expected": "RFC of 10 or 13 characters"
    }
  }
}

​
Description

This endpoint starts a process for extracting tax documents from SAT. Extraction is an asynchronous process that can take several minutes depending on the volume of documents.
The extraction process is asynchronous. Use the returned publicId to check status or configure webhooks to receive notifications.

​
Request

​
subject
object
required
Information of the taxpayer from whom to extract documents
​
credentials
object
required
Credentials to access SAT
​
options
object
required
Extraction options
​
filters
object
Optional filters for extraction

​
Response

​
publicId
string
Unique extraction ID for subsequent queries
​
status
string
Current status: PENDING, PROCESSING, COMPLETED, FAILED
​
createdAt
string
Creation timestamp in ISO 8601 format
​
options
object
Copy of the options sent in the request
​
subject
object
Processed taxpayer information
​
discoveryCount
number
Number of documents found (0 initially)
​
completedCount
number
Number of documents processed successfully
​
failedCount
number
Number of documents that failed to process

​
Examples

curl -X POST "https://api.taxo.co/v1/extractions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "identifier": "ABC010101ABC",
      "name": "Empresa ABC S.A. de C.V."
    },
    "credentials": {
      "type": "CIEC",
      "password": "bXlQYXNzd29yZDEyM0A="
    },
    "options": {
      "informationType": "INVOICE",
      "period": {
        "from": "2024-01-01",
        "to": "2024-12-31"
      },
      "direction": "RECEIVED"
    },
    "filters": {
      "emitters": ["XYZ020202XYZ"],
      "minAmount": 1000
    }
  }'

​
Successful response

{
  "publicId": "JOB20250104123456789A",
  "status": "PENDING",
  "createdAt": "2025-01-04T12:34:56.789Z",
  "options": {
    "informationType": "INVOICE",
    "period": {
      "from": "2024-01-01",
      "to": "2024-12-31"
    },
    "direction": "RECEIVED"
  },
  "subject": {
    "identification": "ABC010101ABC",
    "fullName": "Empresa ABC S.A. de C.V.",
    "personType": "MORAL"
  },
  "discoveryCount": 0,
  "completedCount": 0,
  "failedCount": 0
}

​
Common errors

{
  "error": {
    "code": "INVALID_RFC",
    "message": "The provided RFC does not have a valid format",
    "details": {
      "field": "subject.identifier",
      "provided": "ABC01010",
      "expected": "RFC of 10 or 13 characters"
    }
  }
}

​
Important notes

Passwords: Always encode passwords in base64 before sending them. Plain text passwords will be rejected.
Large periods: For date ranges greater than 3 months, consider splitting the extraction into multiple requests for better performance.
Asynchronous status: Once the extraction is created, use the Check status endpoint to monitor progress.