BlackLine Public API

Documentation for Users

October 25, 2017

Version 1.7

DISCLAIMER. The information in this document is for general guidance only. In no event will BlackLine or the partners or employees thereof be
liable to you or anyone else for any decision made or action taken in reliance on the information in this document.

The contents of this document are confidential; for internal use by BlackLine clients, partners and staff only.
 Confidential

Table of Contents
List of Illustrations ....................................................................................................................................3
Revision History.............................................................................................Error! Bookmark not defined.
BlackLine Public API Overview ...................................................................................................................3
Web Service Architecture..........................................................................................................................4
Features ...............................................................................................................................................4
For the API Client/Developer .....................................................................................................................4
What is the overall process to setup your API access account? ................................................................5
How do you start using our APIs?...........................................................................................................5
How does a developer work with our APIs? ............................................................................................5
How do authentication and authorization work? ....................................................................................6
API Types .................................................................................................................................................6
Security Architecture ................................................................................................................................6
Transport Level Security ........................................................................................................................7
Security Authentication Processing Sequence.............................................................................................8
Client’s System Administrator: Setting up a user for API access ...................................................................9
Authentication REST API Details .............................................................................................................. 12
Route Summary...................................................................................................................................... 13
Route Specifications............................................................................................................................ 13
Rate and Size Limits ................................................................................................................................ 14
Message Rate Limiting ........................................................................................................................ 14
Message Payload Limiting (POST operation: /authorize/connect/token)................................................ 14
HTTP Status Error Codes ......................................................................................................................... 14
Reporting REST API Details ...................................................................................................................... 16
Route Summary...................................................................................................................................... 18
Route Specifications ............................................................................................................................ 19
Rate and Size Limits ................................................................................................................................ 19
Message Rate Limiting ........................................................................................................................ 19
HTTP Status Error Codes ......................................................................................................................... 19
Tasks REST API Details............................................................................................................................. 20
Route Summary...................................................................................................................................... 21
Route Specifications ............................................................................................................................ 21
Message Payload Limiting (POST operation: /tasks/import) .................................................................. 21
HTTP Status Error Codes ......................................................................................................................... 22
Message Payload .................................................................................................................................... 22
FAQ’s ..................................................................................................................................................... 23

@ BlackLine 2017. All rights reserved. Public API User Guide Page 2
 Confidential

List of Illustrations
Figure 1. BlackLine Public API Product Family .............................................................................................4
Figure 2. Web Service Architecture Block Diagram ......................................................................................4
Figure 3. Relationship between a BlackLine API consumer, STS and Public API ..............................................7
Figure 4. STS Authentication Processing Sequence......................................................................................9
Figure 5. As a System Administrator, Navigate to the Users Admin Grid ..................................................... 10
Figure 6. Click the edit icon for the user to whom you wish to extend API access ........................................ 10
Figure 7. Granting API Role Access AND generating an API Key .................................................................. 11
Figure 8. Authorization API Header with Client Secret in Postman ............................................................. 12
Figure 9 Sample Task API message payload containing required fields ....................................................... 13
Figure 10. Authentication API response in Postman .................................................................................. 13
Figure 11. Inserting the Authentication Key into the OAuth2 Authorization Header in Postman for the Report
List service ............................................................................................................................................. 16
Figure 12. Report List API response in Postman ........................................................................................ 16
Figure 13. Inserting the Authentication Key into the OAuth2 Authorization Header in Postman for the Report
Data service ........................................................................................................................................... 17
Figure 14. Report Data API response in Postman for a CSV export type ...................................................... 17
Figure 15. Inserting the API Key into the OAuth2 Authorization Header in Postman .................................... 20
Figure 16. Postman view of the body of the message ................................................................................ 20
Figure 17. JSON content of Task Message................................................................................................. 23

BlackLine Public API Overview

BlackLine is developing an Application Programming Interface (API) to direct interaction between the client’s
BlackLine application environment (and the data therein) without having to use the BlackLine application UI
(user interface). Implementation will be accomplished by BlackLine partners working with BlackLine clients
(or by the client’s own developers in some cases).
Security is assured through the presence of multiple BlackLine hardware firewalls and a specialized BlackLine
deployment of STS (Secure Token Service) whereby a combination of pre-arranged and on-the-fly exchanges
guarantee that the user uploading files to or requesting data from BlackLine is in fact a duly authorized user.
API access to BlackLine will allow near real-time exchange of data that can bring BlackLine functionality
directly in to the client’s own ecosystems.
Access to Tasks via the API will be set up on a per-user basis by the client’s designated BlackLine
administrator who will be working together with BlackLine. The client’s System Administrator will authorize
the user(s) for API access.
The BlackLine Public API is constructed along the lines of a product family. For example, the highlighted
Tasks API in the following diagram is one of multiple BlackLine products that have or will have APIs.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 3
 Confidential

Figure 1. BlackLine Public API Product Family

Web Service Architecture

BlackLine's Public API is based upon a "RESTful" web service architectural pattern. Our web services
implement industry-standard protocols, communication endpoints, and message structures. Our services
are all HTTP-based RESTful APIs which implement the following aspects:
 Every API contract (or service endpoint) implements a URL format, such as
https://api.blackline.com/tasks/{resource}.
 Our APIs are published in a standard internet media type that defines state transition. Our APIs
consume and publish data in JSON format.
 Support standard HTTP verbs (e.g., POST, GET, PUT, PATCH, DELETE).

Figure 2. Web Service Architecture Block Diagram

Features
• API Rate Limiting - Rate limits are divided into specific windows or intervals.
• Complete API documentation - All of our routes, product functionality (resources), message
schemas, HTTP status codes, and code samples are posted on the BlackLine API Developer
Portal.
• Standards-based security: Our services utilize the OAuth 2.0 protocol for authenticating your
REST calls using OAuth 2.0. Our OAuth tokens are claims based.
• All requests are made over HTTPS. Out network communication is over TLS 1.2.
• All responses are in JSON.

For the API Client/Developer

BlackLine’s primary objective was to lower all barriers to start working with the BlackLine Public APIs. We
worked very hard to make it a straight-forward process to help developers become immediately productive

@ BlackLine 2017. All rights reserved. Public API User Guide Page 4
 Confidential

using our APIs, we made the process as straight-forward as possible. Answers to some common questions
are:
What is the overall process to setup your API access account?
1. Initially, BlackLine sets up your BlackLine instance (i.e., your BlackLine software environment) with
the necessary database and security preliminaries to accommodate API users.
2. Consequently, during an integration phone call, you work with BlackLine’s integration team to
configure your API account security. Your company will be granted access to the BlackLine Public
API Management Portal to manage your API account with us.
3. Your company’s designated System Administrator will select each user who will need access to the
API(s), and will
a. Activate the API role for each API (e.g., Tasks or Reporting)
b. Generate an API key (also known as a “client secret”). This key is used to authenticate with
the BlackLine Security Token Service (STS) to authenticate and receive OAuth 2.0
claims-based tokens.
Note: Steps 1 and 2 comprise a one-time setup process. You, as a System Administrator, manage
Step 3 to administer client secrets (i.e., to issue, revoke or re-issue API keys).

How do you start using our APIs?

1. Each API consumer (=user) must obtain an API key (a client secret) - this key is used to authenticate
API consumers who are attempting to call our APIs. You can obtain this API key from an API
Administration portal page hosted on the main BlackLine web site. Access to the API Portal requires
that your BlackLine user profile be set up with the API role by your BlackLine System Administrator.
2. As an API consumer, you can use the BlackLine application to revoke and re-issue new client secrets
and to set up claims from a centralized location.
2. Identify the specific Product API with which you need to work. Route contracts, message schemas,
sample request/response messages (JSON), and API functionality are published on our API
Technical Documentation and will become available as developed.

How does a developer work with our APIs?

1. Host URL - All BlackLine Public API product requests should be issued against a URL: e.g.,
https://api.blackline.com/{API product}/{resource}.
2. Access the BlackLine Public API documentation via our Developer Portal. It provides all information
necessary to assist developers to become immediately productive using our suite of APIs. Our on-
line technical documentation includes, for example, the following information:
• API Route (base URL and resource).
• Request/response structures include sample JSON message and schema definitions.
Note: All response message payloads are expressed in JSON unless otherwise explicitly stated in
the documentation.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 5
 Confidential

How do authentication and authorization work?

1. All communication requires authentication. Developers must first authenticate with the BlackLine
STS and receive an OAuth token before an attempt is made to access any BlackLine Public API
product (refer to security architecture section of this document).
2. OAuth tokens contain claims used to authorize all API access attempts.
OAuth tokens and client secrets (API keys) are always passed in the HTTP message Authorization Header.
The token endpoint can be used to programmatically request tokens. BlackLine is 100% compliant with the
OAuth 2.0 standard and all requests must follow this standard. During an integration call with BlackLine, you
will obtain the following parameters (highlighted in yellow) and you will enter the username and generate
the password:

 grant_type = “password”
 scope = [API Type] + “API “ + [Client_ID] (Client ID provided by the integration team)
 username = BlackLine Application Username (based on users selected to use API)
 password = BlackLine User API Key (self service within Application)
 client_secret (provided by the integration team)

API Types
The following API Types are currently supported:
 Tasks
 Reports

Security Architecture
To support maximum secure communications between customers and partners, BlackLine's Public API
implements both transport and message level security. This approach is chosen to protect the integrity of
the message during in-flight transmission (transport security) and authenticity of requests (message
security).
The BlackLine Security Token Service (STS) is an application service whose primary purpose is to act as an
identity provider responsible to create, sign, issue and verify security tokens as part of a claims-based
identity system.
Our STS has multiple responsibilities, including:
• Authentication of users.
• Manage and authenticate principals (i.e., claims).
• Issue OAuth 2.0 tokens to API consumers.
• Validate tokens.
The following deployment diagram below illustrates the interrelationship between an API consumer,
BlackLine STS, and the BlackLine Public API.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 6
 Confidential

Figure 3. Relationship between a BlackLine API consumer, STS and Public API

Transport Level Security

Transport-level security is a well-known and often-used mechanism to secure HTTP Internet and intranet
communications. BlackLine's transport level security is based upon Transport Layer Security (TLS) that runs
beneath HTTP. All HTTP/S communication between BlackLine and API consumers are over firewall IP-white
listed ranges. Multiple External and Internal firewalls provide physical device-level isolation for various
segments of the transport system.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 7
 Confidential

Security Authentication Processing Sequence

An API consumer's interaction with the BlackLine STS and our API is illustrated in the following sequence
diagram. The communication processing sequence between all three "actors" below illustrates a typical web
service communication session:

Figure 4. STS Authentication Processing Sequence

Step Description

1 API consumer executes an HTTP/S POST to the BlackLine Security Token Service (STS). The consumer
(client) is required to pass the following:
Authorization Header
 Client Secret = integration team will provide this initially
Query String Parameters
 Grant Type = “password”
 Scope = [API Type] + “API “ + Client ID
2 The STS will authenticate the data passed to it from the consumer, and if the credentials are valid,
the STS will return an OAuth 2.0 token back to the consumer via the response message Authorization
Header. The token is used for subsequent communication with the Public API.

3 API consumer initiates an HTTP/S operation to the BlackLine Public API passing the OAuth token
(received at step 2) to a published API endpoint. Note that this call is over TLS 1.2 and must be
transmitted to a BlackLine firewall white listed IP range.

4, 5 The Public API will take the token passed to it from the consumer and subsequently validate the
token regarding its authenticity. If the token is valid, the API will process the consumer's request.

6 A response message is returned to the consumer.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 8
 Confidential

Step Description

1 API consumer executes an HTTP/S POST to the BlackLine Security Token Service (STS). The consumer
(client) is required to pass the following:
Authorization Header
 Client Secret = integration team will provide this initially
Query String Parameters
 Grant Type = “password”
 Scope = [API Type] + “API “ + Client ID
2 The STS will authenticate the data passed to it from the consumer, and if the credentials are valid,
the STS will return an OAuth 2.0 token back to the consumer via the response message Authorization
Header. The token is used for subsequent communication with the Public API.

3 API consumer initiates an HTTP/S operation to the BlackLine Public API passing the OAuth token
(received at step 2) to a published API endpoint. Note that this call is over TLS 1.2 and must be
transmitted to a BlackLine firewall white listed IP range.

4, 5 The Public API will take the token passed to it from the consumer and subsequently validate the
token regarding its authenticity. If the token is valid, the API will process the consumer's request.

6 A response message is returned to the consumer.

Figure 4. STS Authentication Processing Sequence

Client’s System Administrator: Setting up a user for API access

A BlackLine client must designate a System Administrator to work on the connectivity setup. The first step
will be to individually authorize each of the client’s users who will have contact with the API.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 9
 Confidential

Authorization is done per-user, and for each user, per Application. “API Access” is treated as a role so that
API use is not role-specific to other roles, but rather is itself a role. In addition to being authorized to the API
role, the user must be authorized for each BlackLine Application in which the user will touch the API.
(BlackLine’s first developed an API for “Tasks,” and next “Reporting;” Eventually more BlackLine products
will be equipped with API access.)
To set this up, the Administrator must navigate to the System → Users → Users Admin Grid.

Figure 5. As a System Administrator, Navigate to the Users Admin Grid

Then click the pencil icon ( ) to edit the user to whom API access is to be granted.

Figure 6. Click the edit icon for the user to whom you wish to extend API access

Then click to select the API Access in the checkbox closest to the API Access Role, as well as the one(s)
aligned with the product(s) to which API Access is being granted for this user. In the example below, only the
Task API is available to be activated, and we show it selected.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 10
 Confidential

Figure 7. Granting API Role Access AND generating an API Key

Click the Save button at the top of the page to record the just-made selections.
Repeat this process for any other users you wish to authorize for use of the API.

Note: API access will NOT be immediately available, but instead requires that the developer
working on the project (client’s in-house staff or BlackLine partner) first secure the proper
“tokens” from BlackLine to complete the authorization setup.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 11
 Confidential

Authentication REST API Details

The screenshots below illustrate the information required to execute the Reporting API.

Figure 8. Authorization API Header with Client Secret in Postman

@ BlackLine 2017. All rights reserved. Public API User Guide Page 12
 Confidential

Figure 9 Sample Task API message payload containing required fields

Figure 10. Authentication API response in Postman

Route Summary
The following routes are required for communication with the BlackLine Authentication API.

POST operation
https://us2.api.blackline.com/authorize/connect/token

Method Route Parameters Data Expected Return Values (success)

Type

1 POST /authorize/connect/t Authenticatio String HTTP Status Code: 200 (OK).

oken n payload
(JSON array An Access Token, Expiration Time and Token
containing Type will be returned in the response message
authenticatio content. The Access Token and the Token
n Type are used in calls to subsequent API
information). operations.

Authorization
Header

Route Specifications
Service Message Request/Response Guideline
Message parameters will be in JSON format unless otherwise noted. The following guidelines must be met:

@ BlackLine 2017. All rights reserved. Public API User Guide Page 13
 Confidential

1. Sample metadataMust include the following the Header: required HTTP headers for JSON body:
Example: Content-Type: application/json
2. Must follow the JSON message structure as defined in this document.
3. Responses will be returned to the API consumer in JSON format.
Key Points:
 The service will return an Access Token and Token Type in the HTTP message content body that are
used to authenticate subsequent API operations.
 If an error is encountered, an Access Token will not be returned. Instead, an HTTP error status code
will be returned.
Authentication Response
The following is an example of the JSON response from the Tasks Import service endpointAuthentication
API:
{
"access_token": "f3001d24e7cfa75b28064ebc249715c9",
"expires_in": 3600,
"token_type": "Bearer"
}

Rate and Size Limits

Message Rate Limiting
 Throttled by IP
 Throttled by End Point
 Maximum Unauthorized Requests Per Minute = 10
 Maximum Limit Per Minute (authorized) = 100

Message Payload Limiting (POST operation: /authorize/connect/token)

 Maximum payload size <= 50MB

HTTP Status Error Codes

The following table lists the possible HTTP error codes which may be returned. This list is applicable to both
the task ingestion and tasks status API endpoints.
HTTP status codes are always returned via the HTTP response message status code field.

Status Text Description

Code

400 Bad Request Bad request. Message was malformed or incorrect request message.

401 Not Authorized Authentication has failed or was not provided by the external API consumer. In this
event, the response will include a WWW-Authenticate header containing a
challenge related to the requested resource.

403 Forbidden User may not have necessary permission for a resource.

404 Not found Requested resource cannot be found.

405 Method not allowed Request method is not support for the requested resource.

415 Unsupported media The media type is not supported by the resource server.
type

@ BlackLine 2017. All rights reserved. Public API User Guide Page 14
 Confidential

Status Text Description

Code

429 Too many requests Too many requests made by caller to a single web service endpoint.

440 Login timeout The server is unable to validate authentication credentials within a specific
timeframe.

500 Internal server error General error message used to communicate to the API consumer that an
unexpected exception was encountered and to not expect a specific message
related to the error.

503 Server unavailable The web server is currently unavailable.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 15
 Confidential

Reporting REST API Details

The screenshots below illustrate the information required to execute the Reporting API.

Figure 11. Inserting the Authentication Key into the OAuth2 Authorization Header in Postman for the Report List service

Figure 12. Report List API response in Postman

@ BlackLine 2017. All rights reserved. Public API User Guide Page 16
 Confidential

Figure 13. Inserting the Authentication Key into the OAuth2 Authorization Header in Postman for the Report Data service

Figure 14. Report Data API response in Postman for a CSV export type

@ BlackLine 2017. All rights reserved. Public API User Guide Page 17
 Confidential

Route Summary
The following routes are required for communication with the BlackLine Reporting API.

GET operations
https://us2.api.blackline.com/api/queryruns
https://us2.api.blackline.com/api/completedqueryrun/{id}/{export type}

Method Route Parameters Data Expected Return Values (success)

Type

1 GET /api/queryruns String HTTP Status Code: 200 (OK).

Authorization
Header A JSON object will be returned that will include
the following report information:

 end time

 id

 name

 notes

 start time

 status

 message

 export urls (if available)

o CSV

o Excel

o PDF

The Report Id returned in the response is used

along with the export type to retrieve the data of
the report from the completedqueryrun service,
e.g.:
https://us2.api.blackline.com/api/completedquer
yrun/66886/csv
(refer to service endpoint #2 below).

2 GET /api/completedquer Report Id String HTTP Status Code: 200 (OK).

yrun/{ReportID}/{Ex Export Type
port Type} Response will be based on the Export Type
provided, as follows:

 CSV

o Data in CSV text format

 Excel

o Binary Stream of Excel export

format

 PDF
o Binary stream of PDF export
format

@ BlackLine 2017. All rights reserved. Public API User Guide Page 18
 Confidential

Route Specifications
Service Message Request/Response Guideline
Message parameters will be in JSON format unless otherwise noted. The following guidelines must be met:
4. Must include the following the Header: required HTTP headers for JSON body:
Example: Content-Type: application/json
5. Must follow the JSON message structure as defined in this document.
6. Responses will be returned to the API consumer in JSON format.
Key Points:
 The service will return a Report Id in the HTTP message content body. The Report Id is used in the
Completed Query API with the export type in the URL to return the report data.
 If an error is encountered, a Report data will not be returned. Instead, an HTTP error status code will
be returned.

Rate and Size Limits

Message Rate Limiting
 Throttled by IP
 Throttled by End Point
 Maximum Unauthorized Requests Per Minute = 10
 Maximum Limit Per Minute (authorized) = 100

HTTP Status Error Codes

The following table lists the possible HTTP error codes which may be returned. This list is applicable to both
the task ingestion and tasks status API endpoints.
HTTP status codes are always returned via the HTTP response message status code field.

Status Text Description

Code

400 Bad Request Bad request. Message was malformed or incorrect request message.

401 Not Authorized Authentication has failed or was not provided by the external API consumer. In this
event, the response will include a WWW-Authenticate header containing a
challenge related to the requested resource.

403 Forbidden User may not have necessary permission for a resource.

404 Not found Requested resource cannot be found.

405 Method not allowed Request method is not support for the requested resource.

415 Unsupported media The media type is not supported by the resource server.
type

429 Too many requests Too many requests made by caller to a single web service endpoint.

440 Login timeout The server is unable to validate authentication credentials within a specific
timeframe.

500 Internal server error General error message used to communicate to the API consumer that an
unexpected exception was encountered and to not expect a specific message
related to the error.

503 Server unavailable The web server is currently unavailable.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 19
 Confidential

Tasks REST API Details

The screenshots below illustrate the information needed to execute the Tasks API.

Figure 15. Inserting the API Key into the OAuth2 Authorization Header in Postman

Figure 16. Postman view of the body of the message

@ BlackLine 2017. All rights reserved. Public API User Guide Page 20
 Confidential

Route Summary
The following routes are required for communication with the BlackLine Tasks API.

POST operation
https://us2.api.blackline.com/tasks/import
GET Operation
https://us2.api.blackline.com/tasks/import/status

Method Route Parameters Data Expected Return Values (success)

Type

1 POST /tasks/import Tasks String HTTP Status Code: 202 (Accepted).

payload
(JSON array A Job Id will be returned in the response
containing message content. The Job Id is used to check
one or on the status of the submitted batch job. Status
multiple checks are made by executing an HTTP GET
tasks). operation and passing the Job Id as part of the
route - e.g.,
Maximum https://us2.api.blackline.com/tasks/import/status
payload size /2354 (refer to service endpoint #2 below).
<= 50MB

2 GET /tasks/import/status Job Id String HTTP Status Code: 200 (OK).

/{jobid}
Queries batch job process. Sample metadata is
returned from the Tasks Import Status endpoint.

One of the following responses will be returned:

 Queued
 Running
 Error
 Finished
 Terminated
 Canceled
 Unknown

Route Specifications
Service Message Request/Response Guidelines
7. Must include the following content type. Example: Content-Type: application/json
 Regarding POST operations: One or multiple records may be POST(ed) in a JSON array to the Tasks
API ingestion endpoint. In order to optimize processing, we highly recommend that you POST
multiple records to the processing endpoint instead of a single record inside a JSON array. Exact
number of records will vary but total message payload size must NOT exceed 50 MB in size.
 The service will return a Job Id in the HTTP message content body. The Job Id is used to check on
task ingestion status.
 If an error is encountered, a Job Id will not be returned. Instead, an HTTP error status code will be
returned in the response message.

 = 100

Message Payload Limiting (POST operation: /tasks/import)

 Maximum payload size <= 50MB

@ BlackLine 2017. All rights reserved. Public API User Guide Page 21
 Confidential

HTTP Status Error Codes

The following table lists the possible HTTP error codes which may be returned. This list is applicable to both
the task ingestion and tasks status API endpoints.
HTTP status codes are always returned via the HTTP response message status code field.

Status Text Description

Code

400 Bad Request Bad request. Message was malformed or incorrect request message.

401 Not Authorized Authentication has failed or was not provided by the external API consumer. In this
event, the response will include a WWW-Authenticate header containing a
challenge related to the requested resource.

403 Forbidden User may not have necessary permission for a resource.

404 Not found Requested resource cannot be found.

405 Method not allowed Request method is not supported for the resource.

415 Unsupported media The media type is not supported by the resource server.
type

429 Too many requests Too many requests made by caller to a single web service endpoint.

440 Login timeout The server is unable to validate authentication credentials within a specific
timeframe.

500 Internal server error General error message used to communicate to the API consumer that an
unexpected exception was encountered and to not expect a specific message
related to the error.

503 Server unavailable The web server is currently unavailable.

Message Payload
The Tasks API POST endpoint (https://us2.api.blackline.com/tasks/import) will accept an array of tasks
serialized as in JSON format. The image below is the JSON representation of an expected message payload
containing all required fields. Note that the sample below contains mock data for representational purposes
only. One or multiple JSON messages passed to the Tasks API in a JSON array. Maximum payload size <=
50MB.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 22
 Confidential

Task Message – JSON

[
{
"Entity" : "CORP",
"Segment1" : "BlackLine test 7",
"Segment2" : "General Accounting",
"Description" : "Test Tasks API Import 6",
"Preparer" : "Kim.Wilson",
"StartDate" : "12/31/2013",
"DueDateDays" : 1,
"DueTime" : "23:59:00",
"Role1Frequency" : "Monthly",
"Role2Frequency" : "Quarterly",
"Role3Frequency" : "Never",
"Role5Frequency" : "Never",
"Role7Frequency" : "Never"
}
]
Figure 17. JSON content of Task Message

FAQ’s
Q. Is API rate limiting specified per user or globally for the app?
A. Rate limiting is a global function

Q. Do I have to log in to use the API for each session?

A. Your API key and user name must be submitted as part of the handshake that occurs each time you
log in to use the API.

Q. As a user, can I use the Tasks API for reading BlackLine data or just for writing it?
A. Implementation of the Tasks API allows you to load (create) tasks into BlackLine, so it’s just for
writing. Please note that this API is performing an Add function, and any records would be
overwritten if submitted multiple times.

Q. When is it OK to share my API key or credentials?

A. Never. Please do not share your Client Secret (API key) with others, whether privately or in publicly
accessible areas such GitHub. You are responsible to prevent unauthorized use of the API.

Q. Does the BL API involve/use/permit metadata?

A. Yes. In fact, for the Tasks API specifically you need to provide the necessary metadata to create a Task
within BlackLine.

Q. Which import template does version 1.0 of the Task API follow?
A. Currently, the Task API supports the “Tasks Extended” sheet of the latest BlackLine Import Template.
Please see version 7.14 of the BlackLine Import template.

Q. How do I view the status of my API call?

A. You may hit our status endpoint to retrieve information on the status of the process. Furthermore, if
a system administrator would like to view the status of the records they may visit the Import Status
page within the BlackLine application.

@ BlackLine 2017. All rights reserved. Public API User Guide Page 23