The Exchange Rate Broker API provides allows users to create custom exchange rates for a company. For additional configuration information, please see the Currency Admin Configuration page.

Limitations: The API currently allows a maximum of 100 exchange rates per POST request. This API is only available to users who have been granted access by SAP Concur. Access to this documentation does not provide access to the API.

Process Flow

Exchange Rate Broker v4 POST flow

Products and Editions

Concur Expense Professional Edition
Concur Expense Standard Edition
Concur Travel Professional Edition
Concur Travel Standard Edition
Concur Invoice Professional Edition
Concur Invoice Standard Edition
Concur Request Professional Edition
Concur Request Standard Edition

Scope Usage

Name	Description	Endpoint
`expense.exchangerate.writeonly`	Create custom exchange rates.	`POST`

Dependencies

None.

Access Token Usage

This API supports company level access tokens.

Create Custom Exchange Rates

Create a set of custom exchange rates for the given of dates and currency pairs.

Scopes

expense.exchangerate.writeonly - Refer to Scope Usage for full details.

Request

URI

Template

POST {datacenter}/exchangerate/v4/rates

Parameters

None.

Headers

Content-Type: application/json
Authorization: Bearer Token

Payload

Example JSON request body:

{
  "currency_sets": [
    {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }, {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

In case of success, the JSON response body will be the same array of exchange rate items with overallStatus, and individual rate upload statusCode and statusMessage. A bulk upload can be partially successful.

Status Codes

Headers

concur-correlationid is an SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace.
RFC 7231 Content-Type
RFC 7230 Content-Length

Payload

Successfully Created Response:

{
    "overallStatus": "Success",
    "message": "Requests completed successfully",
    "currencySets": [
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "success",
            "statusCode": 200
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Example - Success

Request

POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "currency_sets": [
    {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }
    , {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789

{
    "overallStatus": "Success",
    "message": "Requests completed successfully",
    "currencySets": [
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "success",
            "statusCode": 200
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Example - Partial Success

This example only partially succeeds to create all exchange rates due to an invalid from_crn_code in the first array entry. However, the second array entry is successfully created.

Request

POST https://us.api.concursolutions.com/exchangerate/v4/rates
Accept: application/json
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "currency_sets": [
    {
      "from_crn_code": "INVALID",
      "start_date": "2019-01-01",
      "rate": 1.2,
      "to_crn_code": "EUR"
    }, {
      "from_crn_code": "USD",
      "start_date": "2019-01-01",
      "rate": 1.3,
      "to_crn_code": "CAD"
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 01 Jan 2020 18:50:00 GMT
concur-correlationid: abcd1234-wxyz-6789-abcd-abc123456789

{
    "overallStatus": "Partial Success",
    "message": "Requests completed with errors",
    "currencySets": [
        {
            "from_crn_code": "INVALID",
            "start_date": "2019-01-01",
            "rate": 1.2,
            "to_crn_code": "EUR",
            "statusMessage": "Invalid request received",
            "statusCode": 400
        },
        {
            "from_crn_code": "USD",
            "start_date": "2019-01-01",
            "rate": 1.3,
            "to_crn_code": "CAD",
            "statusMessage": "success",
            "statusCode": 200
        }
    ]
}

Schema

BulkExchangeRateUploadRequest

Name	Type	Format	Description
`currency_sets`	`array`	`ExchangeRateUploadRequest`	Required An array of exchange rate upload requests.

ExchangeRateUploadRequest

Name	Type	Format	Description
`from_crn_code`	`string`	-	Required ISO 4217 Alphabetic code of the currency converting from.
`to_crn_code`	`string`	-	Required ISO 4217 Alphabetic code of the currency converting to.
`start_date`	`string`	`YYYY-MM-DD`	Required UTC time for exchange rate come to be effective.
`rate`	`number`	-	Required Custom exchange rate.

BulkExchangeRateUploadResponse

Name	Type	Format	Description
`overallStatus`	`string`	-	Overall status for this bulk upload.
`message`	`string`	-	Overall message for this bulk upload.
`currencySets`	`array`	`ExchangeRateUploadResponse`	Array of individual upload results.

ExchangeRateUploadResponse

Name	Type	Format	Description
`from_crn_code`	`string`	-	ISO 4217 alphabetic code of the currency converting from.
`to_crn_code`	`string`	-	ISO 4217 alphabetic code of the currency converting to.
`start_date`	`string`	`YYYY-MM-DD`	UTC time for exchange rate come to be effective.
`rate`	`number`	-	Custom exchange rate.
`statusCode`	`number`	-	HTTP status code for uploading this custom currency set.
`statusMessage`	`string`	-	HTTP message for uploading this custom currency set.

Error

Name	Type	Format	Description
`errorId`	`string`	-	The unique identifier of the error associated with the response or is it error response itself.
`errorMessage`	`string`	-	The detailed error message.
`httpStatus`	`string`	-	The HTTP response code and phrase for the response.
`path`	`string`	-	The URI of the attempted request.
`timestamp`	`string($date-time)`	-	The datetime when the error was captured. Example: `2016-10-04T00:53:25.931+0000`
`validationErrors`	`array`	`ValidationError`	Validation errors for this request.

ValidationError

Name	Type	Format	Description
`message`	`string`	-	The detailed message of the validation error.
`source`	`string`	-	The type of validation which failed.