Docs

Transaction Jobs (Beta)

Suggest Edits

The Transaction Jobs API allows you to export large sets of transaction data asynchronously and download the results any time within 24 hours of the initial request. This is useful for protection from long-running requests that may be impacted by unreliable networks.

Base Route/v1/transaction_jobs
EndpointsGET
/v1/transaction_jobs
/v1/transaction_jobs/:id
/v1/transaction_jobs/:id/download

POST
/v1/transaction_jobs

DELETE
/v1/transaction_jobs/:id
ProducesJSON
PaginationNo
Application Permissions Required"API Access: Create, edit, and delete" and access to view the transaction data requested.
OAuth ScopesTRANSACTIONS_READ

Resource Overview

The Transaction Jobs API returns a resource object described by the below attributes, including the status, errors, and any Transaction Query/View API parameters used in the job. Asynchronous job requests can be made for both the Transaction Query and View APIs.

All attributes will be returned in successful GET & POST responses.

AttributeDescriptionExample
job_typeType of job. String. Required."transaction_view_results"
started_atThe start time of the job in UTC. String. ISO 8601 date format."2020-04-15T21:30:16Z"
completed_atThe completed time of the job in UTC. String. ISO 8601 date format."2020-04-15T21:30:17Z"
percent_completePercentage complete. Number.1.0
statusThe current status of the job. String.See "Status" below.
errorsErrors that occurred running the job. Object.See "Errors" below.

Status

StatusDescription
QueuedJob has not yet been processed by Addepar servers.
In Progress - Waiting For CapacityJob has been placed back in queue because there is no available capacity.
In ProgressJob is currently being processed by Addepar servers.
Picked Up By Job RunnerJob has been picked up by the server and is waiting to run.
CompletedJob has finished processing. Results can be retrieved from the URL in the Location header.
CanceledJob was canceled by the user.
Timed OutJob results have expired and results have been deleted. Results are deleted 24 hours after a job is created.
FailedJob processing failed due to a server issue. Error details are unavailable.
RejectedJob exceeds the maximum quota of the queue.
Error CancelledJob canceled due to an error. Details are provided within the error field of the response.
Cancel RequestedJob in progress and has received a request to cancel.
User CancelledJob canceled.

Errors

ParameterDescriptionExample
statusHTTP status code."400"
titleHTTP status title."Bad Request"
detailError details."Invalid portfolio: ENTITY 10"

Relationships

RelationshipDescription
creatorThe user who created the job.
"relationships":{
  "creator":{
    "links":{
      "self":"/v1/jobs/2/relationships/creator",
      "related":"/v1/jobs/2/creator"
    },
    "data":{
      "type":"users",
      "id":"22"
    }
  }
}

Parameters

Required parameters are specified for portfolio view and query jobs within each description.

ParameterDescriptionExample
portfolio_typeRequired for transaction view and transaction query jobs.

Supported types:
-ENTITY
-GROUP
-FIRM

The type of portfolio.		entity
portfolio_idRequired for transaction view and transaction query jobs.

Portfolio IDs can be configured in Addepar. IDs can represent one entity or a group of entities (query jobs only).

If the portfolio_type is FIRM, the portfolio_id must be 1.		1
view_idRequired for transaction view jobs.

ID of the transaction view.		123
output_typeRequired for transaction view jobs.

The output format of the exported result.

Supported types:
-CSV
-TSV
-XLSX		csv
start_dateRequired for transaction view and transaction query jobs.

The start date of the time period of portfolio data. "YYYY-MM-DD."		2016-01-01
end_dateRequired for transaction view and transaction query jobs.

The end date of the time period of portfolio data. "YYYY-MM-DD."		2016-02-02
columnsRequired for transaction query jobs.

List of column attribute keys. [String].		["trade_date", "security"]
filtersOptional for portfolio query jobs.

Filters rows from the result. Array of Objects.

To learn more, reference the Filter Object within Transaction Query Jobs.		[{"attribute": "asset_class", "type": "discrete", "operator": "include", "values": ["Equity", "Fixed Income"]}
sortingsA transactions query sorting may be attached to a transactions query to sort rows. Accepts up to 3 columns to sort by. Array of objects.

Default to trade date.		[{ "attribute": "trade_date", "ascending": false }]
limitThe max number of transactions returned by the query. Number.

Defaults to 1,048,576 for XLSX output type, no limit for other types.		500
include_online_valuationsWhether online snapshots should be returned by the query. Boolean.

Default to false.		true
include_unverifiedWhether unverified transactions should be returned by the query. Boolean.

Default to false.		true
include_deletedWhether deleted online transactions should be returned by the query. Boolean.

Default to false.		true

Create a Transaction View Job

Creates an asynchronous job to extract transaction data for a saved transaction view in Addepar.

📘

Note

Each job has a timeout limit of 4 hours.

POST /v1/transaction_jobs

Example: 

POST https://examplefirm.com/api/v1/transaction_jobs

{
    "data": {
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "transaction_view_results",
            "parameters": {
                "view_id": 5,
                "portfolio_id": 193,
                "portfolio_type": "entity",
                "output_type": "xlsx",
                "start_date": "2024-01-01",
                "end_date": "2024-06-30"
            }
        }
    }
}

HTTP/1.1 202 Accepted

{
    "data": {
        "id": "47d7e547-7f5a-11ef-8162-dde0088e926a",
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "TRANSACTION_VIEW_RESULTS",
            "percent_complete": 0.0,
            "status": "Queued"
        },
        "relationships": {
            "creator": {
                "links": {
                    "self": "/v1/transaction_jobs/47d7e547-7f5a-11ef-8162-dde0088e926a/relationships/creator",
                    "related": "/v1/transaction_jobs/47d7e547-7f5a-11ef-8162-dde0088e926a/creator"
                },
                "data": {
                    "type": "users",
                    "id": "22"
                }
            }
        },
        "links": {
            "self": "/v1/transaction_jobs/47d7e547-7f5a-11ef-8162-dde0088e926a"
        }
    },
    "included": []
}

Response Codes:

  • 202 Accepted: Success. Returns JSON with created job information.
  • 400 Bad Request: Bad JSON: API format, missing parameters or badly formatted parameters
  • 403 Forbidden: User lacks API permission or has not granted the appropriate scope

Create a Transaction Query Job

Creates an asynchronous job to extract transaction data with a query.

POST /v1/transaction_jobs

Example: 

POST https://examplefirm.com/api/v1/jobs

{
    "data": {
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "transaction_query",
            "parameters": {
                "columns": [
                    "trade_date",
                    "direct_owner",
                    "security",
                    "type",
                    "value",
                    "last_edit_by",
                    "last_edit_date"
                ],
                "filters": [],
                "sorting": [
                ],
                // "limit": 1,
                "portfolio_type": "entity",
                "portfolio_id": [
                    12345
                ],
                "start_date": "2024-08-03",
                "end_date": "2024-09-03",
                "include_online_valuations": false,
                "include_unverified": false,
                "include_deleted": true
            }
        }
    }
}

HTTP/1.1 202 Accepted

{
    "data": {
        "id": "204da3ed-7de0-11ef-99fa-25422e3df74b",
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "TRANSACTION_QUERY",
            "percent_complete": 0.0,
            "status": "Queued"
        },
        "relationships": {
            "creator": {
                "links": {
                    "self": "/v1/transaction_jobs/204da3ed-7de0-11ef-99fa-25422e3df74b/relationships/creator",
                    "related": "/v1/transaction_jobs/204da3ed-7de0-11ef-99fa-25422e3df74b/creator"
                },
                "data": {
                    "type": "users",
                    "id": "1000314556"
                }
            }
        },
        "links": {
            "self": "/v1/transaction_jobs/204da3ed-7de0-11ef-99fa-25422e3df74b"
        }
    },
    "included": []
}

Response Codes:

  • 202 Accepted: Success. Returns JSON with created job information.
  • 400 Bad Request: Bad JSON: API format, missing or badly formatted parameters
  • 403 Forbidden: User lacks API permission or has not granted the appropriate scope

Check the Status of a Job

Retrieves the status and parameters for a specific job.

GET /v1/transaction_jobs/:id

Example: 

GET https://examplefirm.com/api/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c

HTTP/1.1 200

{
    "data": {
        "id": "39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c",
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "TRANSACTION_QUERY",
            "percent_complete": 0.0,
            "status": "Queued"
        },
        "relationships": {
            "creator": {
                "links": {
                    "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/relationships/creator",
                    "related": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/creator"
                },
                "data": {
                    "type": "users",
                    "id": "22"
                }
            }
        },
        "links": {
            "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c"
        }
    },
    "included": []
}

Response Codes:

  • 200 OK: Success
  • 404 Not Found: Unable to locate the job with the given id, or user does not have permission to view the given job
  • 403 Forbidden: User lacks API permission or has not granted the appropriate scope

Download the Results of a Job

Returns the results of the given job. If the job has not yet completed, this endpoint will return the job status payload.

📘

Note

Job results are deleted 24 hours after a job is created.

GET /v1/transaction_jobs/:id/download

Example for In Progress Job:

GET https://examplefirm.com/api/v1/jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/download

HTTP/1.1 200

{
    "data": {
        "id": "39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c",
        "type": "transaction_jobs",
        "attributes": {
            "job_type": "TRANSACTION_QUERY",
            "percent_complete": 0.21,
            "status": "In Progress"
        },
        "relationships": {
            "creator": {
                "links": {
                    "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/relationships/creator",
                    "related": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/creator"
                },
                "data": {
                    "type": "users",
                    "id": "22"
                }
            }
        },
        "links": {
            "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c"
        }
    },
    "included": []
}

Example for Completed Job: 

GET https://examplefirm.com/api/v1/jobs/657c5d9b-7f5d-11ef-a01d-2900745d31ff/download

HTTP/1.1 200

Content-Disposition: attachment; file name="transaction_data.xlsx"
Content-Type: application/binary

<DOWNLOAD_CONTENT>

Response Codes:

  • 200 OK: Success. Returns a JSON, CSV, TSV or XLSX as requested.
  • 303 See Other: Completed asynchronous job. Follow the link in the "Location" header to retrieve the results.
  • 404 Not Found: Unable to locate the job with the given id.
  • 410 Gone: Results have expired

Check the Status of All Jobs

Retrieves the status and parameters of all jobs.

GET /v1/transaction_jobs

Example: 

GET https://examplefirm.com/api/v1/transaction_jobs

HTTP/1.1 200

{
    "data": [
        {
            "id": "39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c",
            "type": "transaction_jobs",
            "attributes": {
                "job_type": "TRANSACTION_QUERY",
                "completed_at": "2024-09-30T18:53:10Z",
                "started_at": "2024-09-30T18:53:10Z",
                "percent_complete": 1.0,
                "status": "Completed"
            },
            "relationships": {
                "creator": {
                    "links": {
                        "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/relationships/creator",
                        "related": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/creator"
                    },
                    "data": {
                        "type": "users",
                        "id": "22"
                    }
                }
            },
            "links": {
                "self": "/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c"
            }
        },
        {
            "id": "657c5d9b-7f5d-11ef-a01d-2900745d31ff",
            "type": "transaction_jobs",
            "attributes": {
                "job_type": "TRANSACTION_VIEW_RESULTS",
                "completed_at": "2024-09-30T18:54:22Z",
                "started_at": "2024-09-30T18:54:20Z",
                "percent_complete": 1.0,
                "status": "Completed"
            },
            "relationships": {
                "creator": {
                    "links": {
                        "self": "/v1/transaction_jobs/657c5d9b-7f5d-11ef-a01d-2900745d31ff/relationships/creator",
                        "related": "/v1/transaction_jobs/657c5d9b-7f5d-11ef-a01d-2900745d31ff/creator"
                    },
                    "data": {
                        "type": "users",
                        "id": "22"
                    }
                }
            },
            "links": {
                "self": "/v1/transaction_jobs/657c5d9b-7f5d-11ef-a01d-2900745d31ff"
            }
        }
    ],
    "included": [],
    "links": {
        "prev": null,
        "next": null
    }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: User lacks API permission or has not granted the appropriate scope

Get Job Creator

Retrieves the user who created the job.

GET /v1/transaction_jobs/:id/creator

Example:

GET https://examplefirm.com/api/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/creator

HTTP/1.1 200

{
    "data": {
        "id": "22",
        "type": "users",
        "attributes": {
            "two_factor_auth_enabled": false,
            "admin_access": true,
            "all_data_access": true,
            "login_method": "email_password",
            "email": "[email protected]"
        },
        "relationships": {
            "permissioned_entities": {
                "links": {
                    "self": "/v1/users/22/relationships/permissioned_entities",
                    "related": "/v1/users/22/permissioned_entities"
                },
                "data": []
            },
            "assigned_role": {
                "data": null
            },
            "permissioned_groups": {
                "links": {
                    "self": "/v1/users/22/relationships/permissioned_groups",
                    "related": "/v1/users/22/permissioned_groups"
                },
                "data": []
            }
        },
        "links": {
            "self": "/v1/users/22"
        }
    },
    "included": []
}

Get Job Creator Relationship

Retrieves the relationship of the job creator.

GET /v1/transaction_jobs/:id/relationships/creator

Example:

GET https://examplefirm.com/api/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c/relationships/creator

HTTP/1.1 200

{
    "data": {
        "id": 22,
        "type": "users"
    }
}

Cancel a job

Cancel a job that is has yet to start, is running, or already completed.

DELETE /v1/transaction_jobs/:id

When canceling a job with the status:

  • waiting_for_capacity the job will not run. Status change: user_canceled.
  • in_progress a request to cancel is submitted. Status change:cancel_requested, then user_canceled.
  • completed the results are archived. Status change: user_canceled.

Example

DELETE https://examplefirm.com/api/v1/transaction_jobs/39cee0a7-7f5d-11ef-a01d-45a1a34a1c7c

204 No Content

Response Codes:

  • 204 No Content: Success. Cancel request submitted.
  • 404 Not Found: Cannot locate the job with the given ID, or you don't have permission to view the job.

Updated about 2 months ago