C# Example¶

Below are some samples of how to call the BTQ API using the HttpClient in C#. Please review the Overview for general information about the code samples provided.

Objects¶

First, we define a few objects to handle the request and response bodies for the request we are making.

LoginRequest¶

This object represent the request body for a call to Login. It contains the credentials for the user that we are trying to log in as.

public class LoginRequest
{
    public string Email { get; set; }
    public string Password { get; set; }
}

LoginResponse¶

This object represents the response from a login call. It contains the basic information about the user, the access token for the session, and the list of tenants that the user can access.

public class LoginResponse
{
    public string Status { get; set; }
    public string Email { get; set; }
    public string AccessToken { get; set; }
    ...
}

UserResponse¶

This object represents the information about a user.

public class UserResponse
{
    public string UserId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Status { get; set; }
    ...
}

LogoutRequest¶

This object represents the request body for a call to Logout.

public class LogoutRequest
{
    public string AccessToken { get; set; }
}

Functions¶

Below are a series of functions that reach out to the BTQ API to perform the actions we want to do. Note that we are making use of the Newtonsoft.Json package to serialize and deserialize the objects.

The following method will perform a log in to the BTQ API using a provided username and password.

public async Task<string> Login(string email, string password)
{
    var uri = "https://arc-aegis.billtrust.com/authentication/v1/login";
    var request = new LoginRequest
    {
        Email = email,
        Password = password
    };
    var content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");
    using (var httpClient = new HttpClient())
    {
        using (var httpResponse = await httpClient.PostAsync(uri, content))
        {
            if (!httpResponse.IsSuccessStatusCode)
                throw new Exception($"Error logging in: Received code {httpResponse.StatusCode}");

            var responseBody = await httpResponse.Content.ReadAsStringAsync();
            var response = JsonConvert.DeserializeObject<LoginResponse>(responseBody);
            return response.accessToken;
        }
    }
}

GetUsersForTenant¶

The following method will query the list of users for a specific tenant ID and return the list.

private async Task<List<UserResponse>> GetUsersForTenant(string accessToken, string tenantId)
{
    var uri = $"https://arc-aegis.billtrust.com/user/v1/tenants/{tenantId}/users";
    using (var httpClient = new HttpClient())
    {
        httpClient.DefaultRequestHeaders.Add("X-Billtrust-Auth", accessToken);
        using(var httpResponse = await httpClient.GetAsync(uri))
        {
            if (!httpResponse.IsSuccessStatusCode)
                throw new Exception($"Error getting user information: Received code {httpResponse.StatusCode}");

            var responseBody = await httpResponse.Content.ReadAsStringAsync();
            var response = JsonConvert.DeserializeObject<List<UserResponse>>(responseBody);
            return response;
        }
    }
}

Logout¶

The following method will perform a log out for the provided access token.

public async Task Logout(string accessToken)
{
    var uri = "https://arc-aegis.billtrust.com/authentication/v1/logout";
    var request = new LogoutRequest
    {
        AccessToken = accessToken
    };
    var content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");
    using (var httpClient = new HttpClient())
    {
        using (var httpResponse = await httpClient.PostAsync(uri, content))
        {
            if (!httpResponse.IsSuccessStatusCode)
                throw new Exception($"Error logging out: Received code {httpResponse.StatusCode}");
        }
    }
}

Complete Program¶

Below is a combination of the sample code above into a single runnable sample console application. This code can be compiled and run using .NET Core 2.1. This application has all the classes present in the same file, and it includes all the using statements necessary to run it. The following NuGet packages must be included:

Newtonsoft.Json

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

namespace BtqApiSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                if (args.Length < 3)
                    throw new ArgumentException("Expected call style: dotnet run <tenant> <email> <password>");

                var tenantId = args[0];
                var email = args[1];
                var password = args[2];
                TestBtqApi(tenantId, email, password).GetAwaiter().GetResult();
            }
            catch (Exception ex)
            {
                Console.WriteLine($"{ex.Message}\r\n{ex.StackTrace}");
            }
        }
        private static async Task TestBtqApi(string tenantId, string email, string password)
        {
            var accessToken = await Login(email, password);
            var users = await GetUsersForTenant(accessToken, tenantId);

            Console.WriteLine($"{users.Count} users have access to tenant {tenantId}:");
            foreach (var user in users)
            {
                Console.WriteLine($"{user.FirstName} {user.LastName}");
            }

            await Logout(accessToken);
        }

        private static async Task<string> Login(string email, string password)
        {
            var uri = "https://arc-aegis.billtrust.com/authentication/v1/login";
            var request = new LoginRequest
            {
                Email = email,
                Password = password
            };
            var content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");
            using (var httpClient = new HttpClient())
            {
                using (var httpResponse = await httpClient.PostAsync(uri, content))
                {
                    if (!httpResponse.IsSuccessStatusCode)
                        throw new Exception($"Error logging in: Received code {httpResponse.StatusCode}");

                    var responseBody = await httpResponse.Content.ReadAsStringAsync();
                    var response = JsonConvert.DeserializeObject<LoginResponse>(responseBody);
                    return response.AccessToken;
                }
            }
        }

        private static async Task Logout(string accessToken)
        {
            var uri = "https://arc-aegis.billtrust.com/authentication/v1/logout";
            var request = new LogoutRequest
            {
                AccessToken = accessToken
            };
            var content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");
            using (var httpClient = new HttpClient())
            {
                using (var httpResponse = await httpClient.PostAsync(uri, content))
                {
                    if (!httpResponse.IsSuccessStatusCode)
                        throw new Exception($"Error logging out: Received code {httpResponse.StatusCode}");
                }
            }
        }

        private static async Task<List<UserResponse>> GetUsersForTenant(string accessToken, string tenantId)
        {
            var uri = $"https://arc-aegis.billtrust.com/user/v1/tenants/{tenantId}/users";
            using (var httpClient = new HttpClient())
            {
                httpClient.DefaultRequestHeaders.Add("X-Billtrust-Auth", accessToken);
                using (var httpResponse = await httpClient.GetAsync(uri))
                {
                    if (!httpResponse.IsSuccessStatusCode)
                        throw new Exception($"Error getting user information: Received code {httpResponse.StatusCode}");

                    var responseBody = await httpResponse.Content.ReadAsStringAsync();
                    var response = JsonConvert.DeserializeObject<List<UserResponse>>(responseBody);
                    return response;
                }
            }
        }
    }

    internal class LoginRequest
    {
        public string Email { get; set; }
        public string Password { get; set; }
    }

    internal class LoginResponse
    {
        public string Status { get; set; }
        public string Email { get; set; }
        public string AccessToken { get; set; }
    }

    internal class UserResponse
    {
        public string UserId { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Status { get; set; }
    }

    internal class LogoutRequest
    {
        public string AccessToken { get; set; }
    }
}