Requestbox API documentation

Requestbox

Request Management Platform

Welcome

Welcome to the requestbox REST API. Any POST data will need to be in the JSON format. The response will also return information in JSON. In the case of an error, a relevant status code will be returned and any other relevant information in the response body as JSON.

Some functions can complete with warnings (for example when it can't find a match for a control value when creating a request). Information about these will be returned in the response. It is also possible to prevent the function from completing if there are any warnings by passing the relevant parameters.

Authentication

Authentication is done via Basic HTTP Authorization. The username is ApiKey and the password the value of your key.

Authorization: Basic [Base64EncodedUserNameAndPassword]

To get or generate your API key go to your requestbox API page.

Authentication example


HttpClient httpclient = new HttpClient();

httpClient.baseAddress = httpclient.BaseAddress = new Uri("https://requestbox.net//api/[UrlParameter]/");

string base64 = Convert.ToBase64String(Encoding.UTF8.GetBytes("ApiKey:[MyApiKeyValue]"));

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", base64);


--user 'ApiKey:[MyApiKeyValue]'


authorization: Basic [Base64EncodedUserNameAndPassword]


HTTPRequest r = new HTTPRequest();

Blob headerValue = Blob.valueOf('ApiKey:[ApiKeyValue]');

String authorizationHeader = 'BASIC ' + EncodingUtil.base64Encode(headerValue);

r.setHeader('Authorization', authorizationHeader);

Matching field values

When passing field values, certain fields will attempt to match the incoming value with the value in requestbox. If it can't find a match a warning will be added to the result.

Special cases

User drop down fields: Will try to match on the email or full name of the user

Datastore drop downs: Will need to pass the DatastoreColumnName property. Will attempt to match on the chosen column

Field maps

Field maps can be created in requestbox to create custom mapping rules. You pass this via the FieldMap property. If no direct match is found from the incoming value it will then attempt to match based on the field map.

Custom item and datastore drop downs are currently supported. You can map zero, one or many values to each item.

Limits

There are the following limits on the number of API calls. Per second: 1, Per minute: 60, Per hour: 500

Create a request

https://requestbox.net//api/[UrlParameter]/create-request Post

Creates a request

This function creates a new request. You must provide either the request type id (you can find this on the manage request page in requestbox) or the request type and box name. Optionally you can provide a list of control values.

Body Parameters

RequestTypeId Integer Required (when not passing BoxName and RequestTypeName params)

The Id of the request type

RequestTypeName string Required (when not passing RequestTypeId param)

The name of the request type

BoxName string Required (when not passing RequestTypeId param)

The name of the box the request type belongs to

Status string

The name of the status for the new request. If not included the default status will be used.

SendEmailId integer

The id of an email you want to send after the request is created.

ErrorOnWarning boolean

true or false depending on if you want the request to be created when warnings are found

CustomFieldData object array

Collection of custom field values.

FieldName string required

The name of the field

Value variable

The value of the field

IsUniqueField boolean

true or false depending on if the field should be unique. If a request already exists with this value a new request will not be created

FieldMap string

The name of a field map created in requestbox. This can be used to map incoming values to a fields value when no direct match exists. For example when matching to a drop down items.

FallBackValue variable

A value to use if no valid match can be found with the primary value.

DropDownSettings object

Settings specific to drop down fields

DatastoreColumnName string

The name of the column used for matching incoming values to items

Response Body

Status string

success or error. If ErrorOnWarning is true this will be have the value of error when there are one or more warnings

Message string

Descriptive result message.

Warnings object array

Collection of any warnings detected

Type string

The type of warning

Message string

The warning message

Request object

The created request object

Id integer

The id of the request

RequestTypeId integer

The id of the request type

RequestTypeName string

The name of the request type

BoxName string

The name of the box the request type belongs to

Status status

The status of the request

CreatedDate dateTime

The created date of the request

UpdatedDate dateTime

The updated date of the request

Create a request example


public class CreateRequestInput
{
                        public int RequestTypeId { get; set; }

                        public List<CustomFieldData> CustomFieldData { get; set; } = new List<CustomFieldData>();
}

public class CustomFieldData
{
                        public string FieldName { get; set; }

                        public string Value { get; set; }
}

public void CreateRequest(){
                        CreateRequestInput input = new CreateRequestInput();

                        input.RequestTypeId = 500;

                        input.CustomFieldData.Add(new CustomFieldData {
                        FieldName = "RequestName",
                        Value = "MyReqName"
                        });


                        string jsonPostContent = JsonConvert.SerializeObject(input);

                        StringContent bodyContent = new StringContent(jsonPostContent, Encoding.UTF8, "application/json");

                        var response = _client.PostAsync("create-request", bodyContent).Result;

}


curl --request POST
                                 --url https://requestbox.net//api/[UrlParameter]/create-request
                                 --header 'Accept: application/json'
                                 --header 'Content-Type: application/json'
                                 --data '{
                                 "RequestTypeId":500,
                                 "CustomFieldData":[
                                     {
                                        "FieldName":"RequestName",
                                        "Value":"MyReqName"
                                     }
                                  ]}'


POST https://requestbox.net//api/[UrlParameter]/create-request HTTP/1.1
accept: application/json
content-type: application/json
content-length: 97
Host: requestbox.net

{ "RequestTypeId":500, "CustomFieldData":[ { "FieldName":"RequestName", "Value":"MyReqName" } ]}


public class CreateRequestInput{

                        public integer RequestTypeId { get; set; }

                        public List<CustomField> CustomFieldData {get; set;}

}

public class CustomField {
                        public string FieldName { get; set; }
                        public string Value { get; set; }
}

public static void CreateRequest(){

                        CreateRequestInput input = new CreateRequestInput();
                        input.RequestTypeId = 500;
                        input.CustomFieldData = new List<CustomField>();

                        CustomField requestNameField = new CustomField();
                        requestNameField.FieldName = 'RequestName';
                        requestNameField.Value = 'MyReqName'
                        input.CustomFieldData.add(requestNameField);

                        HttpRequest req = new HttpRequest();

                        req.setEndpoint('https://requestbox.net//api/[UrlParameter]/create-request');
                        req.setMethod('POST');

                        string jsonBody = JSON.serialize(input);
                        req.setBody(jsonBody);

                        Http http = new Http();
                        HTTPResponse res = http.send(req);
}

Example Response


{
                        "status":"success",
                        "message":"Request was created successfully",
                        "warnings": [],
                        "request":
    {
        "id":1000,
        "requestTypeId":500,
        "requestTypeName":"MyRequestType",
        "boxName":"MyBoxName",
        "status":"Submitted",
        "createdDate":"2022-04-14T00:00:00.0000000Z",
        "updatedDate":"2022-04-14T00:00:00.0000000Z"
    }
}


{
                        "status":"success",
                        "message":"Request was created with warnings",
                        "warnings":
                        [
                            {
                                "type": "NoMatchedField",
                                "message": "No field found with name \"RequestName\""
                            }
                        ],
                        "request":
    {
        "id":1000,
        "requestTypeId":500,
        "requestTypeName":"MyRequestType",
        "boxName":"MyBoxName",
        "status":"Submitted",
        "createdDate":"2022-04-14T00:00:00.0000000Z",
        "updatedDate":"2022-04-14T00:00:00.0000000Z"
    }
}


{
                        "status":"error",
                        "message": "Could not find a request type with id 1000"]
}

Get a request

https://requestbox.net//api/[UrlParameter]/get-request?requestId=[RequestId] Get

Gets information about a request

This function gets information about a requst. You must provide the request id.

Parameters

Request Id integer Required

The id of the of the request

Response Body

Status string

success or error.

Message string

Descriptive result message.

Request object

The request object

Id integer

The id of the request

RequestTypeId integer

The id of the request type

RequestTypeName string

The name of the request type

BoxName string

The name of the box the request type belongs to

Status status

The status of the request

CreatedDate dateTime

The created date of the request

UpdatedDate dateTime

The updated date of the request

Get a request example

public void GetRequest(){

                        var response = _client.GetAsync("get-request?requestId=1000").Result;

}


curl --request GET
                         --url https://requestbox.net//api/[UrlParameter]/get-request?requestId=1000

GET https://requestbox.net//api/[UrlParameter]/get-request?requestId=1000 HTTP/1.1
Host: requestbox.net

public static void GetRequest(){
                      HttpRequest req = new HttpRequest();

                      req.setEndpoint('https://requestbox.net//api/[UrlParameter]/get-request?requestId=1000');
                      req.setMethod('GET');

                      Http http = new Http();
                      HTTPResponse res = http.send(req);
}

Example Response


{
                        "status":"success",
                        "message":"Request was retrieved successfully",
                        "request":
    {
        "id":1000,
        "requestTypeId":500,
        "requestTypeName":"MyRequestType",
        "boxName":"MyBoxName",
        "status":"Submitted",
        "createdDate":"2022-04-14T00:00:00.0000000Z",
        "updatedDate":"2022-04-14T00:00:00.0000000Z"
    }
}


{
                        "status":"error",
                        "message": "Could not find request with id 1000"]
}

Search requests

https://requestbox.net//api/[UrlParameter]/search-requests Post

Searches requests and returns any that match the criteria

This function searches requests based on various search criteria. You specify search critera in the body of the request. Results are returned in batches of 100 and you can use the skip parameter to skip records already returned. If no search criteria is specified it will return all requests. Results are ordered by Created Date and then by Id.

Body Parameters

Skip integer

The number of requests to skip

RequestIdList integer array

A collection of ids that the requests belong to

RequestTypeIdList integer array

A collection of request type ids that the requests belong to

CreatedFromDate dateTime

The date that the request must be created after

UpdatedFromDate dateTime

The date that the request must be updated after

CustomFieldFilters object array

Collection of objects that represent filters based on the requests custom fields.

FieldName string required

The name of the field

Value variable

The value the field must match

FieldMap string

The name of a field map created in requestbox. This can be used to map incoming values to a fields value when no direct match exists. For example when matching to a drop down items.

FallBackValue variable

A value to use if no valid match can be found with the primary value.

DropDownSettings object

Settings specific to drop down fields

DatastoreColumnName string

The name of the column used for matching incoming values to items

Response Body

Status string

success or error.

Message string

Descriptive result message.

Total requests integer

The total count of all requests that match the search criteria.

Requests object array

Collection of request objects. Will return maximum of 100 records.

Id integer

The id of the request

RequestTypeId integer

The id of the request type

RequestTypeName string

The name of the request type

BoxName string

The name of the box the request type belongs to

Status status

The status of the request

CreatedDate dateTime

The created date of the request

UpdatedDate dateTime

The updated date of the request

Search requests example



public class SearchRequestInput {
                      public List<int> RequestTypeIdList {get; set;} = new List<int>();
}



public void SearchRequests(){

                      SearchRequestInput input = new SearchRequestInput();

                      input.RequestTypeIdList.Add(500);

                      string jsonPostContent = JsonConvert.SerializeObject(input);

                      StringContent bodyContent = new StringContent(jsonPostContent, Encoding.UTF8, "application/json");

                      var response = _client.PostAsync("search-requests",bodyContent).Result;

}


curl --request POST
                                 --url https://requestbox.net//api/[UrlParameter]/search-requests
                                 --header 'Accept: application/json'
                                 --header 'Content-Type: application/json'
                                 --data '{
                                 "RequestTypeIdList":[500]
                                 }'


POST https://requestbox.net//api/[UrlParameter]/search-requests HTTP/1.1
accept: application/json
content-type: application/json
content-length: 97
Host: https://requestbox.net/

{ "RequestTypeIdList":[500]}


public class SearchRequestsInput{

public List<integer > RequestTypeIdList {get; set;}

}

public static void SearchRequests(){

SearchRequestsInputinput = new SearchRequestsInput();
input.RequestTypeIdList  = new List<integer >();
input.RequestTypeIdList.add(500);

HttpRequest req = new HttpRequest();

req.setEndpoint('https://requestbox.net//api/[UrlParameter]/search-requests');
req.setMethod('POST');

string jsonBody = JSON.serialize(input);
req.setBody(jsonBody);

Http http = new Http();
HTTPResponse res = http.send(req);
}

Example Response


{
                        "status":"success",
                        "message":"Search requests completed successfully",
                        "totalRequests": 2,
                        "requests":
                        [
    {
        "id":1000,
        "requestTypeId":500,
        "requestTypeName":"MyRequestType",
        "boxName":"MyBoxName",
        "status":"Submitted",
        "createdDate":"2022-04-14T00:00:00.0000000Z",
        "updatedDate":"2022-04-14T00:00:00.0000000Z"
    },
                         
    {
        "id":1001,
        "requestTypeId":500,
        "requestTypeName":"MyRequestType",
        "boxName":"MyBoxName",
        "status":"Submitted",
        "createdDate":"2022-04-14T00:00:00.0000000Z",
        "updatedDate":"2022-04-14T00:00:00.0000000Z"
    }
                        ]
}