Skip to main content

Overview

The Offer Identifier API endpoint is hosted as part of the Domestic on Demand (DoD) solution, however can be used independently without onboarding to Domestic on Demand. Colleges can choose to use Coltrane as they do today and still use the Offer Identifier endpoint.

The college is responsible for building a client job or service that can consume the API in order to retrieve the offer identifier. It will be possible to retrieve the offer identifier after an applicant accepts an offer at your institution. This is signaled either through a CCY transaction in Coltrane, or via an OfferAccepted event in Domestic on Demand. The offer identifier will be available for 14 days after the applicant accepts the offer. After 14 days, the offer identifier will be deleted and will no longer be available.

In order to retrieve the Offer Identifier, you must first authenticate using your provided client credentials and subscription key. For details on this process, see Authentication.

With an authentication token and a subscription key, you can call the offeridentifier endpoint passing in the nine-digit Application Number on the route. A successful response will contain the nine-digit offer identifier.

Responses​

The Offer Identifier endpoint will return one of the following responses:

Status CodeDescription
200 OKThe offer identifier was successfully retrieved. The response body will contain the nine-digit offer identifier
400 Bad RequestSome part of the request failed validation and could not be processed. Likely the request contained improperly formatted data, was missing required data, or was invalid given the state of the record in question
401 UnauthorizedThe client credentials or subscription key were not provided or are invalid
404 Not FoundThe offer identifier was not provided by the applicant or the applicant no longer has a program choice with an accepted offer from the college
410 GoneThe offer identifier was previously available, but has since been deleted
429 Too Many RequestsA maximum limit of 5 concurrent requests has been reached, or exceeded the rate limit of 100 requests in a span of 60 seconds (note this limit is independent of the rate limit set for the entire DoD service)
500 Server ErrorThe service experienced an error retrieving the offer identifier. Please retry or contact OCAS

Sample code​

Below is sample code demonstrating how to consume the APIs to first authenticate and then fetch the offer identifier for a given application number. The sample code references the UAT environment and will need to be updated to reference the production environment. Specifications of the two environments can be found here: [UAT | PROD]


using System.Net;
using Newtonsoft.Json;

namespace OfferIdentifierSampleClient
{
    public class SingleClassExample
    {
        private const string ClientId = "<Replace Me>";
        private const string ClientSecret = "<Replace Me>";
        private const string ApimSubscriptionKey = "<Replace Me>";
        private const string Authority = "https://authenticate.uat.ocas.ca/auth";
        private const string TokenEndpoint = "/connect/token";
        private const string GrantType = "client_credentials";
        private const string Scope = "dod_api";

        private const string DomesticApiBaseUrl = "https://apis.uat.ocas.ca/apply/domestic";
        private const string ApplicationNumber = "123456789";
        private static readonly TimeSpan HttpClientTimeout = TimeSpan.FromSeconds(60);

        public static async Task Main()
        {
            using var authHttpClient = new HttpClient()
            {
                Timeout = HttpClientTimeout
            };

            var allInputParams = new List<KeyValuePair<string, string>>
            {
                new ("grant_type", GrantType),
                new ("client_id", ClientId),
                new ("client_secret", ClientSecret)
            };

            HttpContent requestParams = new FormUrlEncodedContent(allInputParams);

            var resp = await authHttpClient.PostAsync(new Uri($"{Authority}{TokenEndpoint}"), requestParams).Result;
            dynamic tokenResponse = JsonConvert.DeserializeObject(resp.Content.ReadAsStringAsync().Result);

            using var domesticApiHttpClient = new HttpClient()
            {
                Timeout = HttpClientTimeout
            };

            domesticApiHttpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {tokenResponse!.access_token}");
            domesticApiHttpClient.DefaultRequestHeaders.Add("Subscription-Key", ApimSubscriptionKey);
            dynamic response = await domesticApiHttpClient.GetAsync($"{DomesticApiBaseUrl}/api/v1/applications/{ApplicationNumber}/offeridentifier").Result;
            if (response.StatusCode == HttpStatusCode.NotFound)
            {
                Console.WriteLine($"{ApplicationNumber}: NotFound");
            }
            else if (response.StatusCode == HttpStatusCode.Gone)
            {
                Console.WriteLine($"{ApplicationNumber}: Gone");
            }
            else if (response.StatusCode == HttpStatusCode.OK)
            {
                Console.WriteLine($"{ApplicationNumber}: {response.Content.ReadAsStringAsync().Result}");
            }
            else
            {
                Console.WriteLine("An error occurred fetching offer identifier for application {ApplicationNumber}");
            }
            Console.WriteLine($"{ApplicationNumber}: {response}");
        }
    }
}