Making Requests
Data Requests
Data requests are at the heart of the Autofy platform. We call them Data requests because they use the /data/ endpoints, as opposed to other endpoints, like /meta/.
Once you've provisioned a company and gotten its endpointID, you can begin pushing or pulling data.
QuickBooks Desktop Requests
For connections to QuickBooks Desktop, in order to process requests through the Agent, you'll need to make sure that:
- The end user's machine is turned on and logged into Windows
- The Agent is running with a valid token entered
- Either the company file you want to connect to is open, or no company files are open (check for details for the specific app you're connecting to in the relevant guides).
See our Agent deployment guide for more detail about specific use cases.
In our API reference, we outline that we support GET, POST, and PATCH. In each, you need to provide path parameters in the URL, and you can optionally include query parameters depending on the call.
Data Definitions
When making POST or PATCH calls, first reference the Meta endpoint to see which fields are supported based on the apps you're integrating to.
Route
https://api.getautofy.com/v2/data/{endpointID}/{objectType}
Path Parameters
There are a few required parameters in the URL path that must be included.
endpointID is a required path parameter for data calls, because it identifies the company file you're trying to interact with.
objectType is also required in the path, because it identifies the kind of data you'd like to work with. Values for this parameter can be found in the Data Definitions section of our guides. The name of each object is the objectType.
Query Parameters
Within a request, you can add query parameters. While this is common among most APIs, there are a few details to note.
IDs: You can send multiple of the same parameter in your request. For example, you may have a defined list of record IDs to GET, so in your request, you would include those IDs as parameters.
modTimeStart and modTimeEnd each take JSON date time string format.
Example: 2019-08-09T00:00:00.0000000-05:00
For a full list of parameters, check out the API reference.
Example: GET One Record
In this example, we'll work with Customers. Use the GET method to get a customer by its ID.
Request:
curl --request GET \
--url 'https://api.getautofy.com/v2/data/abc123/customer?id=93vivinvnis494ivn9nm \
--header 'cache-control: no-cache' \
--header 'x-api-key: {YOUR API KEY}' \
--header 'SchemaVersion: 20.04' \
Here is the JSON response you should expect. There are few things to note about a few standard properties in the response:
MoreDatawill tell you if there are more pages of data available in your request.HasErrorslets you know that at least one error has occurred.RequestIDidentifies the request in our logs. Please be sure to track this for all requests as this will need to be provided to support for troubleshooting.
JSON examples
The JSON below is just an example - please reference our schema definitions and meta API for the latest version.
{
"Self": "http://api.getautofy.com/v2/data/abc123/customer?id=93vivinvnis494ivn9nm",
"Kind": "collection",
"Page": 1,
"MoreData": null,
"HasErrors": false,
"RequestId": "IVBASFHZLJ",
"Contents": [
{
"Object": {
"ID": "93vivinvnis494ivn9nm",
"Name": "Pied Piper, Inc.",
"FullName": "Pied Piper, Inc.",
"Parent": {
"ID": "",
"FullName": ""
},
"Terms": {
"ID": "",
"FullName": ""
},
"CompanyName": "",
"Salutation": "",
"FirstName": "",
"MiddleName": "",
"LastName": "",
"Suffix": "",
"TaxCode": {
"ID": "",
"FullName": ""
},
"ItemSalesTax": {
"ID": "",
"FullName": ""
},
"BillingAddress": {
"Line1": "",
"Line2": "",
"Line3": "",
"Line4": "",
"Line5": "",
"City": "",
"State": "",
"PostalCode": "",
"Country": "",
"Notes": ""
},
"ShippingAddress": {
"Line1": "",
"Line2": "",
"Line3": "",
"Line4": "",
"Line5": "",
"City": "",
"State": "",
"PostalCode": "",
"Country": "",
"Notes": ""
},
"Phone": "",
"Mobile": "",
"AlternatePhone": "",
"Email": "",
"Contact": {
"Name": ""
},
"AlternateContact": "",
"Number": "",
"Balance": "",
"IsActive": "",
"CreatedDate": "",
"LastModifiedDate": "",
"Class": {
"ID": "",
"FullName": ""
}
},
"Errors": null,
"Self": "http://api.getautofy.com/v2/data/abc123/customer?id=93vivinvnis494ivn9nm",
"Kind": "customer"
}
],
"Errors": null
}
Example: GET Many Records
In this example, we'll show the result of requesting many Vendor records. Requests that return more than one record appear as a list inside the Contents node:
{
"Self":"https://api.getautofy.com/v2/data/abc123/vendor",
"Kind":"collection",
"RequestId":"N927HEC6E6",
"Page":1,
"MoreData": null,
"HasErrors": false,
"Contents":[
{
"Object":{
"ID":"8000000C-1583445055",
"CreatedDate":"2020-03-05T21:50:55+00:00",
"LastModifiedDate":"2020-03-05T21:52:35+00:00",
"Name":"Canada Bob's",
"IsActive":"true",
"CompanyName":"Canada Bob's",
"Address":{
"Line1":"Canada Bob's"
},
"EligibleFor1099":"false",
"Currency":{
"ID":"8000001B-1517417375",
"FullName":"Canadian Dollar"
}
},
"Errors":[
],
"Self":"https://api.getautofy.com/v2/data/abc123/vendor?id=8000000C-1583445055",
"Kind":"vendor"
},
{
"Object":{
"ID":"80000004-1520437876",
"CreatedDate":"2018-03-07T15:51:16+00:00",
"LastModifiedDate":"2020-08-13T14:50:04+00:00",
"Name":"Jim's Cabinets",
"IsActive":"true",
"Address":{
"Line1":"1111 106th St.",
"City":"Lakeville",
"State":"MN",
"PostalCode":"55044"
},
"Phone":"952-634-5712",
"EligibleFor1099":"false",
"Currency":{
"ID":"80000096-1517417376",
"FullName":"US Dollar"
}
},
"Errors":[
],
"Self":"https://api.getautofy.com/v2/data/abc123/vendor?id=80000004-1520437876",
"Kind":"vendor"
},
{
"Object":{
"ID":"8000000B-1558730026",
"CreatedDate":"2019-05-24T20:33:46+00:00",
"LastModifiedDate":"2020-07-24T16:00:59+00:00",
"Name":"MN Dept of Revenue",
"IsActive":"true",
"EligibleFor1099":"false",
"Currency":{
"ID":"80000096-1517417376",
"FullName":"US Dollar"
}
},
"Errors":[
],
"Self":"https://api.getautofy.com/v2/data/abc123/vendor?id=8000000B-1558730026",
"Kind":"vendor"
}
],
"HasErrors":false,
"Errors":[
]
}
Example: POST A Customer
Use the /data/ method to insert a Customer. For multiple records, send a JSON array.
https://api.getautofy.com/v2/data/{endpointID}/{objectType}
Here is the payload in your request:
{
"ID": "",
"Name": "Pied Piper, Inc.",
"FullName": "",
"CompanyName": "Pied Piper",
"FirstName": "Richard",
"LastName": "Hendricks",
"BillingAddress": {
"Line1": "123 Middle Out Lane",
"Line2": "",
"Line3": "",
"Line4": "",
"Line5": "",
"City": "Cupertino",
"State": "CA",
"PostalCode": "95015"
},
"Phone": "123 456 7890",
"Balance": 10000,
"IsActive": true
}
Request:
curl --request POST \
--url https://https://api.getautofy.com/v2/data/abc123/customer \
--header 'cache-control: no-cache' \
--header 'content-type: application/json' \
--header 'x-api-key: {YOUR API KEY}' \
--header 'SchemaVersion: 20.04'
--data '{ "ID": "", "ExternalID": "", "Name": "API Created Customer #1", "FullName": "", "CompanyName": "CoName", "FirstName": "Auto", "LastName": "fly", "Phone": "123 456 7890", "Balance": 10000, "IsActive": true}'
Here is the JSON response you should expect:
{
"Self":"http://api.getautofy.com/v2/data/abc123/customer",
"Kind":"collection",
"Page":1,
"MoreData": null,
"HasErrors": false,
"RequestId":"{requestID}",
"Contents":[
{
"Object":{
"ID":"8000000E-1586460270",
"Name":"Pied Piper, Inc.",
"CreatedDate":"2020-04-09T19:24:30+00:00",
"LastModifiedDate":"2020-04-09T19:24:30Z",
"FullName":"Pied Piper, Inc.",
"IsActive":"true",
"BillingAddress":{
"Line1":"123 Middle Out Lane",
"City":"Cupertino",
"State":"CA",
"PostalCode":"95015"
},
"Phone":"123 456 7890",
"Balance":"10000.00",
"ItemSalesTax":{
"ID":"8000000C-1558730027",
"FullName":"MN Tax"
},
"CompanyName":"Pied Piper",
"FirstName":"Richard",
"LastName":"Hendricks",
"TaxCode":{
"FullName":"Tax",
"ID":"80000001-1517417372"
}
},
"Errors":[],
"Self":"http://api.getautofy.com/v2/data/abc123/customer/8000000E-1586460270",
"Kind":"customer"
}
],
"Errors":[]
}
Important Notes
- When sending multiple requests, wait for a response before sending the next request. The agent can handle one request at a time.
- Autofy does not support asynchronous syncing or concurrent requests.
Updated about 1 year ago