Publish Finance Data

With spend information, the Productiv platform enables software discovery and generates insights about purchased applications and their associated costs.

This API can be used to push finance data to Productiv from one or more existing systems.

Prerequisites

  • Before this API can be queried, you should have already set up the application for which you will be publishing finance data. Once thats done you should have a unique appId that can be used to query these APIs. Visit the Set up an Application section for more details.

  • In order to query this API, you would also need to send an access_token as part of the Authorization header. Visit the Authorization section to see the steps for generating an access token.

Publish Finance Data Endpoint

POST https://public-api.productiv.com/services/push/v1/customer/apps/{appId}/finance

Include the following headers and path parameters along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token
Required Scope https://api.productiv.com/connector.write

Path Params

Parameter Description
appId appId represents the App for which the finance data are being pushed. (See Set up an Application)

Request Body Schema

{
    "records": [
        {
            "created": "Timestamp",
            "category": "String",
            "amount": "Double",
            "currency": "String",
            "identifier": "String",
            "name": "String",
            "type": "String",
            "merchant": "String"
        }
    ]
}

Finance Data Record Object

Every finance data record should have the following properties in the object:

Property Datatype Description Optional
created Number Unix timestamp in milliseconds of when the record was created. No
amount Number Amount of the transaction. No
currency String Currency code for the amount based on the ISO 4217 standard (ex. USD, CAD, EUR). No
identifier String Identifier for who/what executed the transaction (ex. user email). No
type String Type of the transaction. Either expense or invoice. No
vendor String Name of the vendor where the transaction took place. No
name String Name associated with the transaction. Yes
category String Category for the transaction. Yes
description String Description of the transaction. Yes
transactionNumber String Identifying number for the transaction. Yes

Example Record Object Schema

{
    "created": 1577836800000,
    "category": "IT Expense:Software & Web Services",
    "amount": 200.15,
    "currency": "USD",
    "identifier": "user@example.com",
    "name": "Example User",
    "type": "expense",
    "vendor": "GitHub"
}

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.

Example Response Schema

{
    "success": true
}

Response Errors

Error Code Error Message Description
400 Bad Request Returned if any invalid/unexpected query parameter/value is present in the request.
401 Unauthorized Returned if access_token used in request is invalid or expired.
403 Forbidden Returned if access_token does not have the required scope to use this API.
404 Not Found Returned if customer or application specified does not exist.
422 Unprocessable Entity Returned if the request payload is invalid
429 Too Many Requests Returned if rate limit has been exceeded

Example Error Response Schema

{
    "code": "401",
    "message": "Invalid access_token",
    "success": false
}

SLA

  • You must only send a batch of finance records not more than 1000 at a time.