Catalog JSON API Documentation

So, you want to develop some tooling around the Catalog API - perhaps some custom reports? Great! This API gives you everything that Catalog has to offer.

Authentication

Visit this page to create an API key. Once you’ve received your key, treat it like a password.

Use SSL for all requests to the API. Non-SSL requests will result in redirects, and your API key will be sent in the clear.

To authenticate, send the API key as a request header. Here’s an example using cURL:

curl https://www.my-catalog.edu/api/v1/products -H 'Authorization: Token token="my-api-key"'

Pagination

All index endpoints support pagination. Specifically, we implement RFC5988.

Pagination Options

You can use ?page= to set the page of data you want to retrieve. If no items exist for that page, the response will be a root key with an empty array.

curl https://www.my-catalog.edu/api/v1/courses?page=2

{
  "courses": []
}

To change the number of items returned for each page, you can use ?per_page=. This defaults to 20 and has a max of 100.

curl https://www.my-catalog.edu/api/v1/courses?per_page=40&page=2

Information about pagination is provided in the Link header. Here is an example of what the header could look like

curl -I https://www.my-catalog.edu/api/v1/courses?page=3

Link: <https://www.my-catalog.edu/api/v1/courses?page=4>; rel="next",  
      <https://www.my-catalog.edu/api/v1/courses?page=15>; rel="last",
      <https://www.my-catalog.edu/api/v1/courses?page=1>; rel="first",
      <https://www.my-catalog.edu/api/v1/courses?page=2>; rel="prev"

Let’s talk about what each link means. rel="next" lets us know that the next page of data is page=4. This make sense given that we requested page 3. rel="prev" lets us know that the page previous to the one we requested is page=2. rel="next" indicates the next page of data to request. rel="last" tells us the last and total number of pages of data that currently exist.

Not all rel= links will exist on every response. For instance, the response for the first page of data will not have rel="first" or rel="prev". The same is true for the last page of data. This means that you can programmatically traverse all pages of data by requesting the first page and continuing to request the rel="next" until the response does not contain a rel="next".

It’s important to note that altering the per_page= will change the total number of pages.

Listing Image

If you are uploading a product image in SVG format. You will need to specify the file type.

curl https://www.my-catalog.edu/api/v1/products -F "course[listing_image]=@somefile.svg;type=image/svg+xml"'

Catalogs

Listing catalogs

Endpoint

GET https://www.my-catalog.edu/api/v1/catalogs

Request

Route

GET https://www.my-catalog.edu/api/v1/catalogs

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this catalog. Integer
created_at The creation date for the catalog. Datetime
updated_at The last time the catalog was updated. Datetime
name The name of the catalog. String
canvas_domain Domain for the corresponding canvas account. String
canvas_id Id for the corresponding canvas account. String
logo URL for the catalog logo. String
locale Three character locale for the catalog. String
url Url for the catalog String
user_defined_fields An array of serialized user defined field records provided to the catalog either through direct assignment or inheritance. Array
user_defined_field[name] Name of the user defined field String
user_defined_field[label] Label that will be shown with the field String
user_defined_field[field_type] HTML input type of the field String
user_defined_field[required] Indicates if the custom field is required Boolean
parent[id] The id of the parent catalog Integer
parent[name] The name of the parent catalog Integer
settings[privacy_policy_url] Url of the privacy policy for this catalog. String
settings[terms_url] Url of the terms used for this catalog. String
settings[currency] Three character currency code. String
settings[time_zone] Timezone configured for this catalog. String
settings[country] Two character country code. String
settings[email_from_name] Name that appears as the sender in emails. String
settings[allow_user_registration] Indicates if new users allowed to enroll classes. Boolean
settings[title_tag] Used for custom titles in HTML. String
settings[meta_description] Used to a meta tag description in HTML. String
settings[custom_head_content] Used to add custom head content to HTML. String
settings[custom_body_content] Used to add custom body content to HTML. String
settings[show_listings_in_parent] Indicates if this catalogs listings will show in a parent catalog. Boolean
settings[skus_enabled] Indicates if the course displays the sku field. Boolean

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: mT4druQGtUQOBDwH4YQqUXhaATHzVNPIgR0A3E8nkx+QAGYdw5LwuVkZHvA14Uwe0/TkcyynWVMjB17xkzWjbQ==
ETag: W/"caa1beea60caebfed1d9a4b5b3e11ad2"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=Z2Zyb2V1akFQSFdlMENBd0NVSFQ3WFdoblVVNk93ZVhRUVV6VEdqYXpsbHBlOFYyQUk5Qi9oL0FqWElLeHVxaHZtRWpYK0RlZlBxOGRBdDhKMDFPTHdYczU3OTdMMkxsbFVON3B6Vks2cXAxS2FGRWtpTDZ6YWpnanJQSVZ6RlZyUGM4T1AweTZzRFgvV1lzMi9yVm9pMmlwSE5OOWFsdkljOGIrOFhuNHFFaUxnNU44YkxhMHB1dldzVEdTUjBULS13UVBPZEhFS0F2akNMZGMwcE81bUdBPT0%3D--c4b79fe46cccee0d6a655c28a5b842f2d62fed0c; path=/; HttpOnly
X-Request-Id: e0ae08c4-3f05-4abe-a57c-0671ddd24c62
X-Runtime: 0.067036
Content-Length: 1651

Body

{
  "catalogs": [
    {
      "id": 17,
      "name": "Domain Account 17",
      "parent": null,
      "created_at": "2020/03/17 19:48:17 +0000",
      "updated_at": "2020/03/17 19:48:17 +0000",
      "canvas_domain": "www.canvas-domain-17.com",
      "canvas_id": 17,
      "settings": {
        "privacy_policy_url": "https://www.instructure.com/policies/privacy/",
        "terms_url": "https://www.instructure.com/policies/acceptable-use",
        "currency": "USD",
        "supported_payment_types": "standard",
        "time_zone": null,
        "country": "US",
        "email_from_name": "Canvas Catalog",
        "email_from_address": "notifications@instructure.com",
        "allow_user_registration": true,
        "title_tag": null,
        "meta_description": null,
        "custom_head_content": null,
        "custom_body_content": null,
        "show_listings_in_parent": true,
        "order_id_prefix": null,
        "inherit_categories": false,
        "inherit_user_defined_fields": false,
        "beta_canvas_domain": null,
        "skus_enabled": false,
        "canvas_enrollment_events": true,
        "include_noncatalog_courses_in_dashboard": true,
        "external_idp_logout_workflow": false,
        "external_registration_url": null,
        "external_registration_public_key": null,
        "redirect_external_registration_condition": "authenticated"
      },
      "user_defined_fields": [
        {
          "list_order": 0,
          "name": "favorite_color",
          "label": "Favorite Color",
          "field_type": "text",
          "required": false,
          "required_message": "Favorite Color is required"
        },
        {
          "list_order": 1,
          "name": "code_of_conduct",
          "label": "Code of Conduct",
          "field_type": "checkbox",
          "required": true,
          "required_message": "You must accept the Code of Conduct."
        },
        {
          "list_order": 2,
          "name": "age",
          "label": "Age",
          "field_type": "text",
          "required": true,
          "required_message": "You must provide an Age."
        }
      ],
      "logo": "https://test-bucket.s3.amazonaws.com/test/logos/506b3b738018b31a0e0cad8c2171497a13f189f6.jpeg",
      "locale": "en",
      "url": "http://www.my-catalog.edu"
    }
  ]
}

Certificates

Creating a Certificate

Endpoint

POST https://www.my-catalog.edu/api/v1/certificates

Parameters

Name Description Type
certificate[listing_id] required Id of the Listing Integer
certificate[name] required Name of the Certificate String
certificate[active] State of the Certificate, defaults to true Boolean
certificate[template] required Template for Certificate contents String
certificate[pdf_settings][orientation] 'Landscape' or 'Portrait' mode for PDF. Defaults to Landscape. String
days_to_expire Days until the certificate expires after it is awarded. Defaults to null. Must not be present when expires_at is present. Integer
expires_at Date of certificate expiration. Defaults to null. Must not be present when days_to_expire is present. Datetime

Request

Route

POST https://www.my-catalog.edu/api/v1/certificates

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "certificate": {
    "listing_id": 28,
    "name": "API Name",
    "active": true,
    "template": "<H1>This is a template</h1>",
    "pdf_settings": {
      "orientation": "Landscape"
    }
  }
}

Response

Status

201

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: uhUxeEEoqbunTDCGQiZlzlfKo56iiTxJAR60iujSR4SmDGeIRZbaIv63BsNV4D54G5vMw2iPpfb4wKasrS9AKA==
ETag: W/"0da4c690174a64325e70a30ea5cb5ef6"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=R3NZVjhVOVR4dmM5VDk5Z3gybVd3OTE5eFJuZFlPdkF1TENNM1hNUk9HNWQvR0hGcnU5b1MvM0ZjSEVlNUVkRlBWNEFMcnRaazJpNFBGY25qOEczOURZTFNYTE8ydDBBdEQwUnlNcGFOVzF0bWhUOUx3d1UyVExqOGRGUk1XcVJQWEJnNVdQSzl3QTJFZzFQdFN4WlJQRTNBazNUMUdRK3hnOG1aa2ZNMGdhaFFPRzR1OGdUdWxHWFFhQVRaWjdwLS1IZE54eU1jTGQ2UXR3ellEQTlkSXdBPT0%3D--c122b6f24590cc75330ed309c13c94d042063b9d; path=/; HttpOnly
X-Request-Id: ea14627b-563f-4271-8f9d-51d6140eba86
X-Runtime: 0.347013
Content-Length: 298

Body

{
  "certificate": {
    "id": 2,
    "listing_id": 28,
    "name": "API Name",
    "active": true,
    "template": "<H1>This is a template</h1>",
    "pdf_settings": {
      "orientation": "Landscape"
    },
    "created_at": "2020/03/17 19:48:17 +0000",
    "updated_at": "2020/03/17 19:48:17 +0000",
    "days_to_expire": null,
    "expires_at": null
  }
}

Completed Certificates

listing a user's completions with a certificate

Endpoint

GET https://www.my-catalog.edu/api/v1/completed_certificates

Parameters

Name Description Type
user_id required Canvas Id of the user Integer
only_certificates Indicates if the courses without certificates should be included, default is to include all courses Boolean

Request

Route

GET https://www.my-catalog.edu/api/v1/completed_certificates?user_id=1&only_certificates=true

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Query parameters

user_id=1
only_certificates=true

Response

Response fields

Name Description Type
canvas_course_id Canvas Course ID Integer
catalog_title catalog course title String
canvas_course_name Canvas Course name String
certificate_url URL for Course Certificate String
canvas_course_workflow_state Canvas Course Workflow State String
completed_at Canvas Course Completion Date Datetime

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: o8+fPZD3IWBsaZPgr+vWIm1XrpanQYpTKC+TXeNC2dsMcwqJ7gxQweJxHu3kK4ZaUdnHQ923mzRtso2NQawZtQ==
ETag: W/"22e4d117899e3b626ed59ea04a542627"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=YVpyRlQxbkk3M29kMjdJdmNBOEExOFJmU2xZYllwREYzUjJWRUUrQWdRaEtYVTRLZlhGOHc4UExBS3JwREJOOW9UbnBKL3RrNDY4ZWNyZDRJZXlINjhMMTEvUEZUYndqTlM1bFppVEF0R3hNZDdqckdXSndJNEhYQVBORnQrL29EMldaSThiWVZ2a202U1dHS2RVbVVwSFAzK3lSVTRoUlMyRWMvWkNnb3RUM0ZzTU1HRlA2L25yWGhhcURHL0owLS05WTh0YTFsMys4SVJ4dUxhY2lTWG1BPT0%3D--98263192c97a1fc7d9a84bc7a5995b4648e62d71; path=/; HttpOnly
X-Request-Id: e71ddcf9-9af6-4789-8c0c-f28ae4a8e0ab
X-Runtime: 0.065186
Content-Length: 262

Body

{
  "completed_certificates": [
    {
      "canvas_course_id": 16,
      "catalog_title": "Course 26",
      "canvas_course_name": "Course 26",
      "certificate_url": "https://www.domain-12.com/certificates/certificate-numero-1-1.pdf",
      "canvas_course_workflow_state": "available",
      "completed_at": null
    }
  ]
}

Courses

Creating a course

Endpoint

POST https://www.my-catalog.edu/api/v1/courses

Parameters

Name Description Type
course[title] required Listing title String
course[description] required Full listing description String
course[path] required Path to the listing. Used in URLs String
course[teaser] required A shorter description of the listing String
course[enrollment_open] Indicates if the listing is current accepting new students Boolean
course[visibility] Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
course[enrollment_cap] A limit for the total number of enrollments Integer
course[enrollment_fee] Enrollment fee Decimal
course[allowed_payment_types] Allowed payment methods Array
course[days_to_complete] The number of days a student has to complete the requirements Integer
course[account_id] The id of the account to associate the listing to. Can be an id of any subcatalog of the catalog making the API request. Defaults to the catalog making the API request. Integer
course[list_order] Order in which the listing is shown in the catalog Integer
course[waitlist] Waitlist enabled (defaults to false) Boolean
course[waitlist_cap] Wait List Limit for the total number of wait listed enrollments Integer
course[listing_image] URL or file upload for the image to be shown with this listing. String
course[tag_names] List of tags applied to this listing Array
course[canvas_course_id] required Id of the related canvas course Integer
course[credits] Credit value of the course Decimal
sku Listing SKU for a course String

Request

Route

POST https://www.my-catalog.edu/api/v1/courses

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "course": {
    "title": "Course 1",
    "description": "This is a very important course.",
    "path": "course-1",
    "canvas_course_id": 10010010,
    "teaser": "This is an example teaser",
    "enrollment_open": true,
    "visibility": "listed",
    "enrollment_cap": 150,
    "waitlist": true,
    "waitlist_cap": 25,
    "enrollment_fee": 49.99,
    "days_to_complete": 45,
    "list_order": 123,
    "credits": 4,
    "sku": "abc1234",
    "tag_names": [
      "Tag",
      "Another Tag"
    ]
  }
}

Response

Response fields

Name Description Type
id Identifier for this listing. Integer
visibility Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
enrollment_open Open for enrollment Boolean
enrollment_cap A limit for the total number of enrollments Integer
waitlist Waitlist enabled Boolean
waitlist_cap Wait List Limit for the total number of wait listed enrollments Integer
title Title of the listing String
enrollment_fee Enrollment fee Decimal
currency The three digit currency code associated to the enrollment fee String
listing_path Path to the listing. Used in URLs String
short_description A short description for this listing String
list_order Order in which the listing is listed in the catalog Integer
tag_names List of tags applied to this listing Array
catalog[id] Id for the catalog that owns this listing Integer
catalog[name] Name for the catalog that owns this listing String
created_at The creation date for the listing. Datetime
updated_at The last time the listing was updated. Datetime
canvas_course[id] Corresponding Canvas id Integer
credits Credit value of the course Decimal
sku Listing SKU for a course String

Status

201

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Location: https://www.my-catalog.edu/api/v1/courses/31
Content-Type: application/json; charset=utf-8
X-CSRF-Token: 7w52Ib6neLCKCkdrQZ6DBtPvNA7PyaSJhACA3c68PmOsbaKovGD4uAsBmckNL5DoGCDpzYUw0B8nKytjCed9lg==
ETag: W/"db42546e93c29bbf6092eba332b1708f"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=VlVXNnVJUkVrTkJ1eXpxMkpLK3M3bWd1S2VOZWZZejQvdnhQY293U0I1SHQwR1Nrd2ViSjZRV3dQQnVWc0FCWG5zL0hpcHJjclpzWks0azViaFJEN1BHM3BSOThxMkxKRGlmUmJISGk4aVYrUG4wQ2VGcDI2U1I1SElhaGJyS01ETGp0c252MGNDK3hxZGY1d0h2QnZ1N2dLUUJ4K2lSWkorY1hKeGFMV2JRMlRHT2JYTk9EMVB2bEx4OXBQZHYxLS1lY1o2bHlMeHNhQnowUkIzRUdKSFN3PT0%3D--771387fcec89cb85c151f4c66dbbd2c12579c579; path=/; HttpOnly
X-Request-Id: 241a2d9d-aa70-40ab-a5d4-80c2cdf6e845
X-Runtime: 0.103916
Content-Length: 668

Body

{
  "course": {
    "id": 31,
    "visibility": "listed",
    "enrollment_open": true,
    "enrollment_cap": 150,
    "description": "This is a very important course.",
    "enrollment_fee": "49.99",
    "created_at": "2020/03/17 19:48:18 +0000",
    "credits": "4.0",
    "updated_at": "2020/03/17 19:48:18 +0000",
    "short_description": "This is an example teaser",
    "listing_path": "course-1",
    "listing_image": null,
    "currency": "USD",
    "catalog": {
      "id": 25,
      "name": "Domain Account 25"
    },
    "type": "Course",
    "title": "Course 1",
    "list_order": 123,
    "waitlist": true,
    "waitlist_cap": 25,
    "sku": "abc1234",
    "show_free_banner": true,
    "image_alt_text": null,
    "allowed_payment_types": [
      "standard"
    ],
    "tag_names": [
      "Tag",
      "Another Tag"
    ],
    "canvas_course": {
      "id": 10010010
    }
  }
}

Deleting a specific course

Endpoint

DELETE https://www.my-catalog.edu/api/v1/courses/:id

Request

Route

DELETE https://www.my-catalog.edu/api/v1/courses/33

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Content-Type: application/x-www-form-urlencoded
Cookie: 

Response

Status

204

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-CSRF-Token: I1euiXCMU4bOy3QN9W1FeVm80MpSeHtMpKf4hQe0062dMn2SbP/6HfiuKpLTvntY7P6ezyfUsYMPBeCzoGIhaA==
Cache-Control: no-cache
Set-Cookie: _gallery_session=eGtYMTBPcHpvNnZtTnU4OXFIUllhS3N5bmhYK3gvVjdLdnZscit2TzQrTUJuOVlEUzNpbzZMTXFHYkNabkVzRFV0OHlHRk05WXRvUVFXcWZzMTBzN2J4dFd6NzBobEtJT0szTzc3dk5hTmZaRmlCai9Fd0lBdGl4MHVsNkdZQ291Y05PK2s0QXhCVW5sVGczbHh3TWR0ak9STzlNK1dmSzhlQXJiSSs4OWloWFFicnkzRjJwM2VOclozd0QvS0x6LS1xcFlwM1JLckQ5N1U5TDBKUmhOTWR3PT0%3D--863d5505eaba1191765ade4625d3cbd886804d99; path=/; HttpOnly
X-Request-Id: a4fdd0fd-5629-4a56-a5f6-e139308670bb
X-Runtime: 0.096274

Getting a specific course

Endpoint

GET https://www.my-catalog.edu/api/v1/courses/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/courses/34

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this listing. Integer
visibility Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
enrollment_open Open for enrollment Boolean
enrollment_cap A limit for the total number of enrollments Integer
waitlist Waitlist enabled Boolean
waitlist_cap Wait List Limit for the total number of wait listed enrollments Integer
title Title of the listing String
enrollment_fee Enrollment fee Decimal
currency The three digit currency code associated to the enrollment fee String
listing_path Path to the listing. Used in URLs String
short_description A short description for this listing String
list_order Order in which the listing is listed in the catalog Integer
tag_names List of tags applied to this listing Array
catalog[id] Id for the catalog that owns this listing Integer
catalog[name] Name for the catalog that owns this listing String
created_at The creation date for the listing. Datetime
updated_at The last time the listing was updated. Datetime
canvas_course[id] Corresponding Canvas id Integer
credits Credit value of the course Decimal
sku Listing SKU for a course String

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: /w9jgyV55XI3Wv2rfcs7xCRwY+Dsv6bi1hA/K7aDmYV8Ty27Cb4Jb93kGj4f71n0nh+wXQs+u/F01aLPmRhVbg==
ETag: W/"e4239e9a825b901c2b991092ba17a1fd"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=ZHRRR3p0ZEg1ejBPV0UzQ2F5cGFUUGhGNkhzTU1lS1FNTytwQitSbWhCV3VId1RWN2VjdW1JZHdBeUROSHlCNmFteTYvM1Z4RUJNUHFmWVlNaTQ2aTRKQ0YxSVdrZ3BUV3lXL2xHOXlPWFpjS01VM0lmZWJDdnJyeE96S1FoYkNDdUJ1RFR0aTY0MTVOZysvWm1iUklKUFZXeHR4M3Fjb2lmNWVtRkdGUmFMZHBWMGxkaFBwNHhyZnRqZ1JYQmpTLS1QZTJBS1JXcUdMWmo4bU1DQitIU1JBPT0%3D--21e6e41189c4d364b8443bac191bcde3bc50bc88; path=/; HttpOnly
X-Request-Id: 68f9e720-dd84-4ce8-abba-f0aa71341e8b
X-Runtime: 0.048226
Content-Length: 637

Body

{
  "course": {
    "id": 34,
    "visibility": "listed",
    "enrollment_open": true,
    "enrollment_cap": null,
    "description": "description_32",
    "enrollment_fee": "0.0",
    "created_at": "2020/03/17 19:48:18 +0000",
    "credits": "3.0",
    "updated_at": "2020/03/17 19:48:18 +0000",
    "short_description": "teaser_32",
    "listing_path": "course-path-32",
    "listing_image": null,
    "currency": "USD",
    "catalog": {
      "id": 29,
      "name": "Domain Account 30"
    },
    "type": "Course",
    "title": "Course 32",
    "list_order": null,
    "waitlist": false,
    "waitlist_cap": null,
    "sku": "sku_21",
    "show_free_banner": true,
    "image_alt_text": null,
    "allowed_payment_types": [
      "standard"
    ],
    "tag_names": [
      "Tag",
      "Another Tag"
    ],
    "canvas_course": {
      "id": 21
    }
  }
}

Listing courses

Endpoint

GET https://www.my-catalog.edu/api/v1/courses

Request

Route

GET https://www.my-catalog.edu/api/v1/courses

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: yEbm3gN0ASQYzvTds/t8mOrlQgSpaY30Gcwk8NzeMzu247p1fxal9Eelkmv7ZxY4aUj2WEXRbCIXO2jRm+FodA==
ETag: W/"0f445260461309fd37a2211152951cc9"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=c1QvUXNBYUJUakJsOE9WZVBNaGxVMWl3Y0xnejluZlI3ampOMjhQczFEcEF1WHoxQ2hwK1Q5Um1LaG9qbDRLVGIvUUh4blFaWC92QW50aXdsb2lpZTRXL3IyQmVSZ3lJVWVpcFpLV0Y1c2VQWGlUQm9RY3F1WTV3RE5XQThBM0d5UWcxak52NXJDRmNOaUtxdXY5UkUrVkJvNTdJYWFLSEFyd084aHo5bDJINkpqY3dnYUFXUnJZcmxBL3MzMS84LS10b0tKL2paTEd4SXRkY2RQTVFvaGh3PT0%3D--6c99ee671f1c778e9d8c1814cd9cb315f9e06b1b; path=/; HttpOnly
X-Request-Id: 8bc2e1f0-054d-4cef-8a67-0ce9c79dfa66
X-Runtime: 0.053524
Content-Length: 640

Body

{
  "courses": [
    {
      "id": 35,
      "visibility": "listed",
      "enrollment_open": true,
      "enrollment_cap": null,
      "description": "description_33",
      "enrollment_fee": "0.0",
      "created_at": "2020/03/17 19:48:18 +0000",
      "credits": "3.0",
      "updated_at": "2020/03/17 19:48:18 +0000",
      "short_description": "teaser_33",
      "listing_path": "course-path-33",
      "listing_image": null,
      "currency": "USD",
      "catalog": {
        "id": 30,
        "name": "Domain Account 31"
      },
      "type": "Course",
      "title": "Course 33",
      "list_order": null,
      "waitlist": false,
      "waitlist_cap": null,
      "sku": "sku_22",
      "show_free_banner": true,
      "image_alt_text": null,
      "allowed_payment_types": [
        "standard"
      ],
      "tag_names": [
        "Tag",
        "Another Tag"
      ],
      "canvas_course": {
        "id": 22
      }
    }
  ]
}

Updating Course SKUs

Endpoint

PUT https://www.my-catalog.edu/api/v1/courses/update_skus

Parameters

Name Description Type
attachment required CSV containing a Catalog Course ID and Catalog Course SKU header file

Request

Route

PUT https://www.my-catalog.edu/api/v1/courses/update_skus

Headers

Authorization: Token token="my-token"
Content-Type: multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1
Host: www.my-catalog.edu
Cookie: 

Body

------------XnJLe9ZIbbGUYtzPQJ16u1
Content-Disposition: form-data; name="attachment"; filename="missing_header1.csv"
Content-Type: text/plain
Content-Length: 69

[uploaded data]
------------XnJLe9ZIbbGUYtzPQJ16u1--

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: fA5oB1ZYQgYbxZg6leIw9YGYYq6GgxCxKWnunvFUDGwwY+DUzOUB6VvTwNdurXucFjGCeYK/5yfDl74/jrMGCg==
ETag: W/"bdb16dd71a50715529a61f5bf87438b4"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=bnRjcFRGWnhRMkkvUE5KM1BDaVd4Z1dvMXJRUDBQUWFyMzBWWFljWUk4cURXb0RvTlhKaDg5MWx4MW1qUHhYR1hsZzhDdWV6Y3ZjYXJqK3RydDQzczV6dlRlNzdFcGJaTzc5OWdFRGpQdVhrSzNmYkIzZVhXb0JRRVZlTnU4a1F1Y1p4dGpYV0M4bmZsRWpNQWZLYzJvQkxRbnBCQ1VnUXB1QkxITUxXMW9hcDRDYkIxaG4rd00xc01EUFpMMVBrLS1kYjg2U0FmUE5VUUQ5bFhFQzRxNDdnPT0%3D--0c96da14f65e2d8caa90607abe49d08be05bc741; path=/; HttpOnly
X-Request-Id: 417be105-b465-4f05-96df-04b57d3a08d5
X-Runtime: 0.037514
Content-Length: 206

Body

{
  "progress": {
    "id": 2,
    "account_id": 27,
    "canvas_user_id": null,
    "completion_percent": null,
    "workflow_state": "queued",
    "payload": {
    },
    "created_at": "2020/03/17 19:48:18 +0000",
    "updated_at": "2020/03/17 19:48:18 +0000"
  }
}

Updating a course

Endpoint

PUT https://www.my-catalog.edu/api/v1/courses/:id

Parameters

Name Description Type
course[title] Listing title String
course[description] Full listing description String
course[path] Path to the listing. Used in URLs String
course[teaser] A shorter description of the listing String
course[enrollment_open] Indicates if the listing is current accepting new students Boolean
course[visibility] Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
course[enrollment_cap] A limit for the total number of enrollments Integer
course[enrollment_fee] Enrollment fee Decimal
course[allowed_payment_types] Allowed payment methods Array
course[days_to_complete] The number of days a student has to complete the requirements Integer
course[account_id] The id of the account to associate the listing to. Can be an id of any subcatalog of the catalog making the API request. Defaults to the catalog making the API request. Integer
course[list_order] Order in which the listing is shown in the catalog Integer
course[waitlist] Waitlist enabled (defaults to false) Boolean
course[waitlist_cap] Wait List Limit for the total number of wait listed enrollments Integer
course[listing_image] URL or file upload for the image to be shown with this listing. String
course[tag_names] List of tags applied to this listing Array
course[canvas_course_id] Id of the related canvas course Integer
course[credits] Credit value of the course Decimal
sku Listing SKU for a course String

Request

Route

PUT https://www.my-catalog.edu/api/v1/courses/32

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "course": {
    "title": "Course 1",
    "description": "This is a very important course.",
    "path": "course-1",
    "canvas_course_id": 10010010,
    "teaser": "This is an example teaser",
    "enrollment_open": true,
    "visibility": "listed",
    "enrollment_cap": 150,
    "waitlist": true,
    "waitlist_cap": 25,
    "enrollment_fee": 49.99,
    "days_to_complete": 45,
    "list_order": 123,
    "credits": 4,
    "sku": "abc1234",
    "tag_names": [
      "Tag",
      "Another Tag"
    ]
  }
}

Response

Status

204

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-CSRF-Token: G/+L0e6zVj/d7t7LdFagi9ctRLDk/U3vwrGmQn0am02j+7fjNK2RTNRmElTaC8cnfwv7Can2esA4UmR7jPJ7Zw==
Cache-Control: no-cache
Set-Cookie: _gallery_session=alUvWDhQUW5VVXc5c2w0UnV1ZFF3Qmt2eFNQQlJHMGtaYmNCMjIvTHUxcXhKdnhwaGpmNVBuZi83V1YzVmJZOFZtYTlYRFg5eUNJRVhiQWg4dVU1eUNSL0FkRU1YUlhMcXZ1aXZrc2xqZmYyWThUMUxaeGgwZk5CNXYvdCs0NUUxakRvMkZFVGxZSTVGamV5RGk2Y2JVTXJVZ0JlaExVZ1JwcHFDVTliRUFja0ZBNDBndlQ4bjlxeHFNbXJPVjBjLS1xclE3ZEVMM0UxdGRFT1JkYXBlNmx3PT0%3D--28f7ecb915e463cdacac322ee9a793c921be759b; path=/; HttpOnly
X-Request-Id: 40052acc-d62c-4149-8cef-67c95e58da38
X-Runtime: 0.085276

Enrollments

Creating an enrollment

Endpoint

POST https://www.my-catalog.edu/api/v1/enrollments

Parameters

Name Description Type
create_order Create an order record for this enrollment, defaults to true Boolean
send_email Send an enrollment email to the user, defaults to true Boolean
enrollment[listing_id] required Id of the Listing Integer
enrollment[canvas_user_id] required Id of the Canvas user Integer

Request

Route

POST https://www.my-catalog.edu/api/v1/enrollments

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "enrollment": {
    "listing_id": 26,
    "canvas_user_id": 1
  }
}

Response

Response fields

Name Description Type
id Identifier for this enrollment Integer
user[id] Corresponding Canvas user id for this enrollment. Integer
listing[id] Identifier for the listing Integer
listing[title] The name of the listing String
listing[type] The type of listing (Course or Program) String
listing[canvas_course_id] Canvas course ID (nil for Program enrollments) String
enrolled_at The time of enrollment (UTC) Datetime
status Enrollment status (active or dropped) String

Status

201

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: MGV2XICHxtnRNF8iiAFe5lz7MoU7Ur72F0awxfTAg5knLgTDzNebeLnut6ViuAJ3HJ+9j00RhiMkhdLTSYGf3w==
ETag: W/"47f78e085b5008c96390838f35f0d421"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=cDQ5SU9idjFsTGRkM2s0YUdZaEpzV2NXbC8vRU1LQk9EQ1oxdmdUT01OSEExY09NdVpnSWplNE1BZDNOWkx0TFpvSC83SzZNaE5pL2xBMEZIRWhOdVU2R2lUQ01hZmRCb2RXTmhrME1XTDBVODRxc0xQZW8zNU9WbjMvVk14cllnSEFXS2Z5M2oyRTQzU1Q1RkdKRW1DaTlvY0JKeDJlNkpMb09VNUF4bWZPOGZoNmhKY0dTWWE5TllMaUNMZnBRLS1TK29xL0UzUUJ0UkZESDFhVzhQbUZ3PT0%3D--d678ccf43991b6ebcb989de942dce91b6ceb1f71; path=/; HttpOnly
X-Request-Id: 75aca679-12bb-4876-ac34-a99b50672c2c
X-Runtime: 0.133249
Content-Length: 177

Body

{
  "enrollment": {
    "id": 4,
    "user": {
      "id": 1
    },
    "listing": {
      "id": 26,
      "title": "Course 25",
      "type": "Course",
      "canvas_course_id": 15
    },
    "enrolled_at": "2020/03/17 19:48:16 +0000",
    "status": "active"
  }
}

Deleting an enrollment

An additional request must be made to Canvas to delete the enrollment and remove it from the Catalog Student Dashboard

Endpoint

DELETE https://www.my-catalog.edu/api/v1/enrollments/:id

Request

Route

DELETE https://www.my-catalog.edu/api/v1/enrollments/3

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Content-Type: application/x-www-form-urlencoded
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this enrollment Integer
user[id] Corresponding Canvas user id for this enrollment. Integer
listing[id] Identifier for the listing Integer
listing[title] The name of the listing String
listing[type] The type of listing (Course or Program) String
listing[canvas_course_id] Canvas course ID (nil for Program enrollments) String
enrolled_at The time of enrollment (UTC) Datetime
status Enrollment status (active or dropped) String

Status

204

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-CSRF-Token: tz3paTpzLpGvifdvoEokKafixtoq3Y2vccltvXZVsm+EUH+ugYKxi1zPg1807DrI3mJvilYdP5rn0D7NIXqEVw==
Cache-Control: no-cache
Set-Cookie: _gallery_session=QlEvVlU1OWYxOWFEbXRLWHkrVzVyM3JXSDN0VWo1aXJzOCtPQVQ1TExLUmVUV25yVmNoNjA0d2N5UkR1aG84ekYydDJFMDQvM1pSTWhrZDVwdjlBRHNZZDY1T3BVNVFRMnJuQkZYKzZoT1V1Q2tvNlB3Z3Y3eDJWRHFlQno5WDY4OUhsVkNJSWUvVUJyS3B2MTNaVXlvZXlrbFYwQ2tvNEpmYUNnbU1zOFFQWFpoWTNvWHZBRmpaTjhla1owYVBkLS1UT1VJYjI1Z2NzQkpEZFRVaC9UcnpBPT0%3D--1d1bde6eb15cf68db787f4e8510ae5c25aef7a38; path=/; HttpOnly
X-Request-Id: 8cfb5cc6-55eb-48a8-bae8-a6106352d554
X-Runtime: 0.069022

Getting a specific enrollment

Endpoint

GET https://www.my-catalog.edu/api/v1/enrollments/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/enrollments/1

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this enrollment Integer
user[id] Corresponding Canvas user id for this enrollment. Integer
listing[id] Identifier for the listing Integer
listing[title] The name of the listing String
listing[type] The type of listing (Course or Program) String
listing[canvas_course_id] Canvas course ID (nil for Program enrollments) String
enrolled_at The time of enrollment (UTC) Datetime
status Enrollment status (active or dropped) String

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: Q7/hLcHQ6wO3qCRB5jY4f1XKpDPWDT9GKTDYUTYaXSgMTs6YhhwB00aqCaIXniOJ6S0K49NsW7Nh3GGcB7+Xew==
ETag: W/"21c202e8e1806fcc5c49ff43d8e2475d"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=VkZZdVpIaTdNeWczaVJUZ09Vc2plYzFDKzFTdnROUU12TGJQU2QyS3Q2dkxwWG9PejI4dWk5WUpIWHVnbkVqTTMvY2pKTTBSbTZ4amw1LzJCOVduZWZ1ZGI5VHk1QTc4SlNvWmx6T0JVemNXL2taMkpyVFdiMEs0bFY0VmJxSXhpQnd1WFlqVUZBYzhjL2VTaFYyTk1XbnRQUnR4TDhyUWVuQnl4dTExL21VNmZobDJVb2hGUHZzLzgreHhSSTFMLS1wV1VHaDkxVkVCWnJoUGkrVFppYjZnPT0%3D--d6830aeb745c539ce6705e7e0934989ae2aeb69e; path=/; HttpOnly
X-Request-Id: 148082d0-0677-4579-8cc9-d0f4ca391fdc
X-Runtime: 0.060924
Content-Length: 177

Body

{
  "enrollment": {
    "id": 1,
    "user": {
      "id": 1
    },
    "listing": {
      "id": 23,
      "title": "Course 22",
      "type": "Course",
      "canvas_course_id": 12
    },
    "enrolled_at": "2020/03/17 19:48:15 +0000",
    "status": "active"
  }
}

Listing enrollments

Endpoint

GET https://www.my-catalog.edu/api/v1/enrollments

Parameters

Name Description
listing_id Only include enrollments for the specified listing (optional, Integer)

Request

Route

GET https://www.my-catalog.edu/api/v1/enrollments

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: RVPH66uVkvb0jlb5r8jEDvjnsUIKduOa2nx5R9qcRau4fYjux1jv57UoN7XJPuWV4wkZJTff4/eBfV1kSKO+Hg==
ETag: W/"7af93a6ebd0e652c5ff14d948847ca3b"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=QyszUDRHOXVBVUhKQ1A1bFA0cElDdFFub1IwdExrcUVRZkh3RWVrUXpydVE5NmRwQlovaklyM0tVNnJNbFJEcUlOKzNZSXpWWC9Jb2ZxM09NWDRieFBiTitqb0ZaaStDSWRCbEpFM2RLOUdtVWkvdXRIYlBTZWxoRlVQSzRDNXpjbnhYR1Z5QWh6bjNHN0lPbXAyUG5lc21NZGxDRnNlcWJ2MHdlaGpXM1JubVZyOXpGSGdmbkZZRHNPU001MjhlLS1GZDVJeHJ3Vm15VnJrUkxqbkF5bFJ3PT0%3D--b86d24f86460cf1c8bbfe0072e93bfef8b8c5e13; path=/; HttpOnly
X-Request-Id: ceaf5b58-ab42-41b5-8220-191774f95511
X-Runtime: 0.065728
Content-Length: 180

Body

{
  "enrollments": [
    {
      "id": 2,
      "user": {
        "id": 2
      },
      "listing": {
        "id": 24,
        "title": "Course 23",
        "type": "Course",
        "canvas_course_id": 13
      },
      "enrolled_at": "2020/03/17 19:48:15 +0000",
      "status": "active"
    }
  ]
}

Orders

Getting a specific order

Endpoint

GET https://www.my-catalog.edu/api/v1/orders/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/orders/1

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this order. Integer
full_id Full ID for this order, including prefix. String
catalog_id DEPRECATED: Use catalog['id'] instead. Integer
catalog[id] Identifier for the catalog the order is linked to Integer
catalog[name] Name of the catalog this order is linked to String
user[id] Canvas ID of the user who placed the order Integer
user[name] Name of the user who placed the order String
user[email] E-mail address of the user who placed the order String
listings Array of purchased listings (courses and programs). Fields below: Array
listing[id] Identifier for a listing purchased with this order Integer
listing[canvas_course_id] Canvas course ID associated to this listing Integer|null
listing[title] The name of the listing String
listing[amount] Listing price at the time of purchase Decimal
promotions Array of promotions used. Fields below: Array
promotion[id] Identifier for a promotion used with this order Integer
promotion[code] Promo code used for this order String
promotion[amount] Discount amount Decimal
payments Array of payments. Fields below: Array
payment[reference_id] Identifier from the payment redirector String
payment[status] Status of the payment. Can be success, error, or pending. String
payment[amount] Amount of the payment Decimal
total Total cost charged to the user Decimal
currency Currency used for the transaction String
purchased_at Time the transaction was successfully completed. This field is nil for unsuccessful or unpaid orders. Datetime
created_at Time the order was initiated. Datetime

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: BCnIpJLAere4/UkJNiaTRCUZ2SpKOTvxB9RiNxZ/xH17GUCPbfRZmVB8UwM0FNMeNVakV+k/yc2ll7duLEZkNQ==
ETag: W/"47e22887339da2efd302035dffe2ae28"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=cVJPbDY0QUhaZ2c4R0p3SjFZR3gzdnJxTjlSdlJSV0hWRll1eHBYWXZIUEljSXp3U2kxOVJTNjVmR09pZFhJSFd2SjVVWFJvYTVFM1h6YjJIb2dvdGM2ejlSRlR3b0pOL3FrOUpQS3VtUWljL3c0eWlmTGl0ellWeHJMSG9FNFpLY2RZUVhjMjAyc2VaQ3dRUnVKcDVUVzdPbTAreXpZTS9FNnp4ZDJEOHRHOFJLNU5ndzAvVzA2enJ1VS82S1lQLS1BaTNwKzFac1Z6WVkxRS9Ic1VhaWhBPT0%3D--5aeaaf7d0d054fa13033eb96be545f4335a4f479; path=/; HttpOnly
X-Request-Id: 20a33a99-bc05-4433-9822-16baf406fe8e
X-Runtime: 0.133675
Content-Length: 483

Body

{
  "order": {
    "id": 1,
    "full_id": "1",
    "catalog_id": 1,
    "catalog": {
      "id": 1,
      "name": "Domain Account 1"
    },
    "user": {
      "id": 1,
      "name": "Saul Goodman",
      "email": "bettercall@saul.com"
    },
    "listings": [
      {
        "id": 1,
        "canvas_course_id": 1,
        "title": "Course 1",
        "amount": "100.0"
      }
    ],
    "promotions": [
      {
        "id": 1,
        "code": "PROMO1",
        "amount": "-10.0"
      }
    ],
    "payments": [
      {
        "reference_id": "123",
        "status": "success",
        "amount": "90.0"
      }
    ],
    "total": "90.0",
    "currency": "USD",
    "purchased_at": "2020/03/17 19:48:13 +0000",
    "created_at": "2020/03/17 19:48:13 +0000"
  }
}

Listing orders

Endpoint

GET https://www.my-catalog.edu/api/v1/orders

Parameters

Name Description
from Earliest date/time to return (optional, String). Suggested format YYYY-MM-DDTHH:MM:SSZ, e.g. 2018-01-01T00:00:00Z. System time zone is UTC.
to Latest date/time to return (optional, String). See 'from' above for format.
canvas_user_id Return only orders for the specified Canvas user ID (optional, String|Array)
completed When set, only return orders that were completed successfully (optional)

Request

Route

GET https://www.my-catalog.edu/api/v1/orders

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: zQVbjGwwjVIu23AcQjJaBwJIkXdr/CM6A0u4IrBcqfgeRuHrA59K73D5rhg6PWyP28d4XS9FuNIlx4PoCV4fRg==
ETag: W/"29328be2c32dd3d452f1d3055ab2c850"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=a0dFaTZoVHZnemN2a2VKVWV3a2pJU2pwRlhoWkppNDVZaklWVHh1VnNieHNmT2VNdVVTMk10VlZZZnJzSHlEeUNzM2tkcXdtMGJQUzJPMGozY1FSb3pyckFTV09SZ2N1SWt2SUZEUC9tenpMODMveGVhMGxKT1J0WkQ1cE5mZ2U2cGsyM3hZZEdOSFdIVFpFSHUvYmxWWXBhMzcxNWhPZjNhSzdFbHl1dlNkcmxqUk9GRjZDZUx5TnFadm96R2s5LS1VT0tzNDcvVU94dHVRTzhPSFcweENnPT0%3D--b97c80a071d2824f0b3a90871297129269475fa5; path=/; HttpOnly
X-Request-Id: 53315c6a-1466-49a0-82de-c7e3309ab254
X-Runtime: 0.064809
Content-Length: 486

Body

{
  "orders": [
    {
      "id": 2,
      "full_id": "2",
      "catalog_id": 2,
      "catalog": {
        "id": 2,
        "name": "Domain Account 2"
      },
      "user": {
        "id": 1,
        "name": "Saul Goodman",
        "email": "bettercall@saul.com"
      },
      "listings": [
        {
          "id": 2,
          "canvas_course_id": 2,
          "title": "Course 2",
          "amount": "100.0"
        }
      ],
      "promotions": [
        {
          "id": 2,
          "code": "PROMO2",
          "amount": "-10.0"
        }
      ],
      "payments": [
        {
          "reference_id": "123",
          "status": "success",
          "amount": "90.0"
        }
      ],
      "total": "90.0",
      "currency": "USD",
      "purchased_at": "2020/03/17 19:48:13 +0000",
      "created_at": "2020/03/17 19:48:13 +0000"
    }
  ]
}

Programs

Creating a program

Endpoint

POST https://www.my-catalog.edu/api/v1/programs

Parameters

Name Description Type
program[title] required Listing title String
program[description] required Full listing description String
program[path] required Path to the listing. Used in URLs String
program[teaser] required A shorter description of the listing String
program[enrollment_open] Indicates if the listing is current accepting new students Boolean
program[visibility] Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
program[enrollment_cap] A limit for the total number of enrollments Integer
program[enrollment_fee] Enrollment fee Decimal
program[allowed_payment_types] Allowed payment methods Array
program[days_to_complete] The number of days a student has to complete the requirements Integer
program[account_id] The id of the account to associate the listing to. Can be an id of any subcatalog of the catalog making the API request. Defaults to the catalog making the API request. Integer
program[list_order] Order in which the listing is shown in the catalog Integer
program[waitlist] Waitlist enabled (defaults to false) Boolean
program[waitlist_cap] Wait List Limit for the total number of wait listed enrollments Integer
program[listing_image] URL or file upload for the image to be shown with this listing. String
program[tag_names] List of tags applied to this listing Array
program[requirement_ids] Ordered array of listing IDs that represent requirements for completing the program Array
program[sequential] Indicates if students are required to complete requirements in order Boolean

Request

Route

POST https://www.my-catalog.edu/api/v1/programs

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "program": {
    "title": "Program 1",
    "description": "This is a very awesome program.",
    "path": "program-1",
    "teaser": "This is an example teaser",
    "enrollment_open": true,
    "visibility": "listed",
    "enrollment_cap": 150,
    "waitlist": true,
    "waitlist_cap": 12,
    "enrollment_fee": 49.99,
    "days_to_complete": 45,
    "list_order": 123,
    "requirement_ids": [

    ],
    "sequential": true,
    "tag_names": [
      "Tag",
      "Another Tag"
    ]
  }
}

Response

Response fields

Name Description Type
id Identifier for this listing. Integer
visibility Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
enrollment_open Open for enrollment Boolean
enrollment_cap A limit for the total number of enrollments Integer
waitlist Waitlist enabled Boolean
waitlist_cap Wait List Limit for the total number of wait listed enrollments Integer
title Title of the listing String
enrollment_fee Enrollment fee Decimal
currency The three digit currency code associated to the enrollment fee String
listing_path Path to the listing. Used in URLs String
short_description A short description for this listing String
list_order Order in which the listing is listed in the catalog Integer
tag_names List of tags applied to this listing Array
catalog[id] Id for the catalog that owns this listing Integer
catalog[name] Name for the catalog that owns this listing String
created_at The creation date for the listing. Datetime
updated_at The last time the listing was updated. Datetime
sequential Indicates if students are required to complete requirements in order Boolean
requirements A nested array of the programs requirements. This includes courses and subprograms which can be distinguished by the type key. Array
credits Cumulative credit value of the program's requirements Decimal

Status

201

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Location: https://www.my-catalog.edu/api/v1/programs/22
Content-Type: application/json; charset=utf-8
X-CSRF-Token: 14MsJk9ZkJ28IDZ21pw3ozz2ygZz8mpDJNvXAik3RuTWCpMcYsICk1rk11fyob+1pUP5k4DcJiurqNn6HJuIzw==
ETag: W/"ff0d9960353705ea44c5ef85b145154c"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=N3lXUVRoSXh1VXpQckhaYmlob0krZFpzNTZWQ1AxeXVYb2J2Tk81TDRaeUxReU1qTzg3eGFwRWxkb0R3cloxYzMxN0Zhbk56L3NQK0grM2kwZS80YzJ3WEF0eHU1NWl0Z2JGN3NjcDErdjRFK24zeGt1N1ovTUkwZVAvQ21aNGxIUjBoQmNzd1d6WTI1ak1xTFI3bm8rMWY5azdCRnZSMHBwSUEya2t2cmIyVmE4OFRKd0pSUTE0TEhicG1CMG96LS0remZDOE10dkY3cDZBbmhvc2R4ekVRPT0%3D--28f58d1ac5429927cfd0b4d145da6c903edc63e1; path=/; HttpOnly
X-Request-Id: 4ff6073d-ea7e-4ea4-b184-c4f5d86f2871
X-Runtime: 0.133122
Content-Length: 667

Body

{
  "program": {
    "id": 22,
    "visibility": "listed",
    "enrollment_open": true,
    "enrollment_cap": 150,
    "description": "This is a very awesome program.",
    "enrollment_fee": "49.99",
    "created_at": "2020/03/17 19:48:15 +0000",
    "credits": null,
    "updated_at": "2020/03/17 19:48:15 +0000",
    "short_description": "This is an example teaser",
    "listing_path": "program-1",
    "listing_image": null,
    "currency": "USD",
    "catalog": {
      "id": 7,
      "name": "Domain Account 7"
    },
    "type": "Program",
    "title": "Program 1",
    "list_order": 123,
    "waitlist": true,
    "waitlist_cap": 12,
    "sku": null,
    "show_free_banner": true,
    "image_alt_text": null,
    "allowed_payment_types": [
      "standard"
    ],
    "tag_names": [
      "Tag",
      "Another Tag"
    ],
    "sequential": true,
    "requirements": [

    ]
  }
}

Deleting a specific program

Endpoint

DELETE https://www.my-catalog.edu/api/v1/programs/:id

Request

Route

DELETE https://www.my-catalog.edu/api/v1/programs/16

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Content-Type: application/x-www-form-urlencoded
Cookie: 

Response

Status

204

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-CSRF-Token: x4NJanX+3f6bcrQPi2HSoDnVFnd3w891XZOdnQM2FyyJ+1/zqLyADg5eUr+odUGsJCIvWgsE7/Ec0pKNJ6Ow2Q==
Cache-Control: no-cache
Set-Cookie: _gallery_session=WENuOWliNW5uRUE1TXU3alVmalhZb3NBVytzVzdrWFdEalZlV0ovYlFLdkhRSHlXNHdzdGV0ZkVDdGZZK1VGWUFuZzBzZ2FXQTF2cjJkeUc4dStFWjRzVm94WWtMMmtXTEJWMnlIbWtOWTBOd2Z4SDZKSjBkZWdERXBvdWtpKzQzckdpc0k5bWx5WmhOUFYvREROL2k3WmJ5SUZrUXJqZEJ2RnRRZHpYTmZQY3lOVVhZY3RQMTJ2ZEFFOFZveTJILS1RaDZySGx1ZFZpTU5vcGt2aFlRTm1BPT0%3D--856c7661f213c09388dfbc071d2782649190f338; path=/; HttpOnly
X-Request-Id: 93232a5c-eb58-4639-85f9-f5687484760b
X-Runtime: 0.097765

Getting a specific program

Endpoint

GET https://www.my-catalog.edu/api/v1/programs/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/programs/4

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this listing. Integer
visibility Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
enrollment_open Open for enrollment Boolean
enrollment_cap A limit for the total number of enrollments Integer
waitlist Waitlist enabled Boolean
waitlist_cap Wait List Limit for the total number of wait listed enrollments Integer
title Title of the listing String
enrollment_fee Enrollment fee Decimal
currency The three digit currency code associated to the enrollment fee String
listing_path Path to the listing. Used in URLs String
short_description A short description for this listing String
list_order Order in which the listing is listed in the catalog Integer
tag_names List of tags applied to this listing Array
catalog[id] Id for the catalog that owns this listing Integer
catalog[name] Name for the catalog that owns this listing String
created_at The creation date for the listing. Datetime
updated_at The last time the listing was updated. Datetime
sequential Indicates if students are required to complete requirements in order Boolean
requirements A nested array of the programs requirements. This includes courses and subprograms which can be distinguished by the type key. Array
credits Cumulative credit value of the program's requirements Decimal

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: EjFV7gfEdesrhBLcOlo2GbnZMC+TXsvhk6dBcHybEa9X1yKK9EfoVXQfPDrvIsPYT/7xDVig9NfHIWwXltXElg==
ETag: W/"b73c610d60b92b7fd1e8831e6d55ccee"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=MElzQW9Ub21VMm8zbWxhVkNiQ01nMVJ6THFpNjBTeDNxMi9jN1R3Ri9YaGo3VzNnRWVtQ3BNbFVPNUM1ZW96V1JMSlByVkV5am1BeDhtS0dWZHFhM3RUSStCSVZvTEx2NGtPek40RUMxK1Arc0ZUNmU0aWlTNkZxZ2ZtUWo4VDUyZTVlbGNaV2xlcjhxVmsxU3FUVTZ4bE9TY1NIM3NqZkdmYlE2L3h1RnYxdEV6YU9SUk1wZFllM3JPNlNYWUJhLS14SkhLRVQ3V2h4NXlTY1d0eG9wdEpRPT0%3D--9fe3a9f58493aca205b27e442488f02bf6121a0c; path=/; HttpOnly
X-Request-Id: fcc971ef-c826-4818-b052-44d2f700c323
X-Runtime: 0.131876
Content-Length: 972

Body

{
  "program": {
    "id": 4,
    "visibility": "listed",
    "enrollment_open": true,
    "enrollment_cap": null,
    "description": "description_4",
    "enrollment_fee": "0.0",
    "created_at": "2020/03/17 19:48:14 +0000",
    "credits": "9.0",
    "updated_at": "2020/03/17 19:48:14 +0000",
    "short_description": "teaser_4",
    "listing_path": "program-path-4",
    "listing_image": null,
    "currency": "USD",
    "catalog": {
      "id": 4,
      "name": "Domain Account 4"
    },
    "type": "Program",
    "title": "Program 4",
    "list_order": null,
    "waitlist": false,
    "waitlist_cap": null,
    "sku": null,
    "show_free_banner": true,
    "image_alt_text": null,
    "allowed_payment_types": [
      "standard"
    ],
    "tag_names": [
      "Tag",
      "Another Tag"
    ],
    "sequential": true,
    "requirements": [
      {
        "id": 5,
        "type": "Program",
        "title": "Program 5",
        "requirements": [
          {
            "id": 7,
            "type": "Course",
            "title": "Course 7",
            "canvas_course": {
              "id": 3
            }
          }
        ]
      },
      {
        "id": 6,
        "type": "Program",
        "title": "Program 6",
        "requirements": [
          {
            "id": 8,
            "type": "Course",
            "title": "Course 8",
            "canvas_course": {
              "id": 4
            }
          },
          {
            "id": 9,
            "type": "Course",
            "title": "Course 9",
            "canvas_course": {
              "id": 5
            }
          }
        ]
      }
    ]
  }
}

Listing programs

Endpoint

GET https://www.my-catalog.edu/api/v1/programs

Request

Route

GET https://www.my-catalog.edu/api/v1/programs

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 3
Content-Type: application/json; charset=utf-8
X-CSRF-Token: NTVjVCouy3Ni+L8xG0Y8alg5S06YQV2qitX48RoLl5LlU3HcC7aYbhcomjlp/+HhjM/LbYXD6xczYMBcqM3X+A==
ETag: W/"880b7c32c69cd4d684f9b9e26b9feb32"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=L29OdDZuM3Y4VFp5YldVR2ZoaWswQ0NRbnMwa1NVM0Nwa2s2QWx4NCs0bFpUZncwOGdGRU5ka2Q0RW5kZjZ4SHZPTE1QNDM3S1FkWU9US01ib01yRGM2M2tFTityUUEwMy8xekUva3RlWjlhbHhaNGJYV2RMRFUxYlo2RktPUThJWjNOdlJpVCtCaUtpcFFRMktZTGNjMjdURTNkTjlsVjhhU1B5dDE4Q3hPTVB3YVlDNlZKZ2hzNnVNUjhwRm8wLS1IaWZVOUJ4Wk9nVXhZb0NXd3dJZlhnPT0%3D--052c10e3baa87b6fdeb4e24d00c7171d22ff0799; path=/; HttpOnly
X-Request-Id: 2fb9f30d-65ee-41af-a58d-8294c451de5f
X-Runtime: 0.168959
Content-Length: 2431

Body

{
  "programs": [
    {
      "id": 10,
      "visibility": "listed",
      "enrollment_open": true,
      "enrollment_cap": null,
      "description": "description_10",
      "enrollment_fee": "0.0",
      "created_at": "2020/03/17 19:48:14 +0000",
      "credits": "9.0",
      "updated_at": "2020/03/17 19:48:14 +0000",
      "short_description": "teaser_10",
      "listing_path": "program-path-10",
      "listing_image": null,
      "currency": "USD",
      "catalog": {
        "id": 5,
        "name": "Domain Account 5"
      },
      "type": "Program",
      "title": "Program 10",
      "list_order": null,
      "waitlist": false,
      "waitlist_cap": null,
      "sku": null,
      "show_free_banner": true,
      "image_alt_text": null,
      "allowed_payment_types": [
        "standard"
      ],
      "tag_names": [
        "Tag",
        "Another Tag"
      ],
      "sequential": true,
      "requirements": [
        {
          "id": 11,
          "type": "Program",
          "title": "Program 11",
          "requirements": [
            {
              "id": 13,
              "type": "Course",
              "title": "Course 13",
              "canvas_course": {
                "id": 6
              }
            }
          ]
        },
        {
          "id": 12,
          "type": "Program",
          "title": "Program 12",
          "requirements": [
            {
              "id": 14,
              "type": "Course",
              "title": "Course 14",
              "canvas_course": {
                "id": 7
              }
            },
            {
              "id": 15,
              "type": "Course",
              "title": "Course 15",
              "canvas_course": {
                "id": 8
              }
            }
          ]
        }
      ]
    },
    {
      "id": 11,
      "visibility": "listed",
      "enrollment_open": true,
      "enrollment_cap": null,
      "description": "description_11",
      "enrollment_fee": "0.0",
      "created_at": "2020/03/17 19:48:14 +0000",
      "credits": "3.0",
      "updated_at": "2020/03/17 19:48:14 +0000",
      "short_description": "teaser_11",
      "listing_path": "program-path-11",
      "listing_image": null,
      "currency": "USD",
      "catalog": {
        "id": 5,
        "name": "Domain Account 5"
      },
      "type": "Program",
      "title": "Program 11",
      "list_order": null,
      "waitlist": false,
      "waitlist_cap": null,
      "sku": null,
      "show_free_banner": true,
      "image_alt_text": null,
      "allowed_payment_types": [
        "standard"
      ],
      "tag_names": [

      ],
      "sequential": true,
      "requirements": [
        {
          "id": 13,
          "type": "Course",
          "title": "Course 13",
          "canvas_course": {
            "id": 6
          }
        }
      ]
    },
    {
      "id": 12,
      "visibility": "listed",
      "enrollment_open": true,
      "enrollment_cap": null,
      "description": "description_12",
      "enrollment_fee": "0.0",
      "created_at": "2020/03/17 19:48:14 +0000",
      "credits": "6.0",
      "updated_at": "2020/03/17 19:48:14 +0000",
      "short_description": "teaser_12",
      "listing_path": "program-path-12",
      "listing_image": null,
      "currency": "USD",
      "catalog": {
        "id": 5,
        "name": "Domain Account 5"
      },
      "type": "Program",
      "title": "Program 12",
      "list_order": null,
      "waitlist": false,
      "waitlist_cap": null,
      "sku": null,
      "show_free_banner": true,
      "image_alt_text": null,
      "allowed_payment_types": [
        "standard"
      ],
      "tag_names": [

      ],
      "sequential": true,
      "requirements": [
        {
          "id": 14,
          "type": "Course",
          "title": "Course 14",
          "canvas_course": {
            "id": 7
          }
        },
        {
          "id": 15,
          "type": "Course",
          "title": "Course 15",
          "canvas_course": {
            "id": 8
          }
        }
      ]
    }
  ]
}

Updating a program

Endpoint

PUT https://www.my-catalog.edu/api/v1/programs/:id

Parameters

Name Description Type
program[title] Listing title String
program[description] Full listing description String
program[path] Path to the listing. Used in URLs String
program[teaser] A shorter description of the listing String
program[enrollment_open] Indicates if the listing is current accepting new students Boolean
program[visibility] Indicates if the listing is visible in the web UI. Possible values: listed, unlisted, hidden String
program[enrollment_cap] A limit for the total number of enrollments Integer
program[enrollment_fee] Enrollment fee Decimal
program[allowed_payment_types] Allowed payment methods Array
program[days_to_complete] The number of days a student has to complete the requirements Integer
program[account_id] The id of the account to associate the listing to. Can be an id of any subcatalog of the catalog making the API request. Defaults to the catalog making the API request. Integer
program[list_order] Order in which the listing is shown in the catalog Integer
program[waitlist] Waitlist enabled (defaults to false) Boolean
program[waitlist_cap] Wait List Limit for the total number of wait listed enrollments Integer
program[listing_image] URL or file upload for the image to be shown with this listing. String
program[tag_names] List of tags applied to this listing Array
program[requirement_ids] Ordered array of listing IDs that represent requirements for completing the program Array
program[sequential] Indicates if students are required to complete requirements in order Boolean

Request

Route

PUT https://www.my-catalog.edu/api/v1/programs/3

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "program": {
    "title": "Program 1",
    "description": "This is a very awesome program.",
    "path": "program-1",
    "teaser": "This is an example teaser",
    "enrollment_open": true,
    "visibility": "listed",
    "enrollment_cap": 150,
    "waitlist": true,
    "waitlist_cap": 12,
    "enrollment_fee": 49.99,
    "days_to_complete": 45,
    "list_order": 123,
    "requirement_ids": [

    ],
    "sequential": true,
    "tag_names": [
      "Tag",
      "Another Tag"
    ]
  }
}

Response

Status

204

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-CSRF-Token: RzFZ7RvdUliVp+opz3NNSuF37T7v/xUe4xAX7Ef4yJ3psEEGzn+DeJ/B10vb5LccveeLGU4kudu3owOm2i55/A==
Cache-Control: no-cache
Set-Cookie: _gallery_session=VlNaOVJPVW4zYldYRldwbFVzbGtSMmV4endSeXhvRVN6Y2NUbzhaVEJ2S0RISGxFOW0yQlZEWTgwT0YrVS90L3RFVThUMG0vN2JCWkY1US9panBDa3hIbGtQZHpCVkJnNnQ2N254b0JZd3ZZaG82TkR1L0R1QmgybzI3SVFYcDF0QytRN0QzTGZZL2Vsc0Q1dHVJTnNVZUZPeC9KNjRmMUVUaFcwYmkwZGx1TXA0ZkVaSEFjdzVzSHRtY0YyUi9WLS1wTms2OU1LUkNadWFhUmJoMnhDYTBRPT0%3D--af02145aeca8402c3bbbc28503636fc764be2468; path=/; HttpOnly
X-Request-Id: 7816e3bd-68d7-47a6-8ce8-6366cb6dcf85
X-Runtime: 0.136021

Progresses

Getting a specific progress

Endpoint

GET https://www.my-catalog.edu/api/v1/progresses/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/progresses/1

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Progress ID Integer
account_id Catalog Account ID Integer
canvas_user_id The Canvas User ID of the user who initiated the job Integer
completion_percent The completion percent of the job Integer
workflow_state The status of the progress String
payload Any data or errors returned by the job Array
created_at The creation date for the progress job Datetime
updated_at The last time the progress job was updated Datetime

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: luSr/BUjnWTKQtqqE7zO1DYcVlWddWrG57xSXVo4wFtCVke6xZ8BYetjR0SOqCO2YCeLcTTGAmGETgERQ7qidg==
ETag: W/"69a44110a49791aabd1797b0ca0c0dbb"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=TW55YkowaU1BaFRqK0FoVVBNK09DL3JBWDUzNUQ2ZlZDbmlFSDJPS05mZ3BMSGx6SzA2QWZ5aFFFdmNnVVYzWGxMMVIzRkVpdVkrYzBVbTZlMHcvL3JnR1dnMzQ3dG1LNlRINGNaQkd2bkZ2TTlzQkFYME10WlRUanBNRU9iY2I4TmJEMStMVFk4c3lxaUlUVGJqWEJYYTdqeWxGR2t0VWs0T0FOQmR0MmFMUldJdDVNUk1nQU11cFp5RUxVbjNhLS0rdWJ3bGMzUkd0aDAydmh4NGNUdEFRPT0%3D--cb20ede497f1da8df844a83941e0dd85c9d52d74; path=/; HttpOnly
X-Request-Id: 50964659-7976-4988-8427-ef1348808fc9
X-Runtime: 0.031753
Content-Length: 206

Body

{
  "progress": {
    "id": 1,
    "account_id": 24,
    "canvas_user_id": null,
    "completion_percent": null,
    "workflow_state": "queued",
    "payload": {
    },
    "created_at": "2020/03/17 19:48:18 +0000",
    "updated_at": "2020/03/17 19:48:18 +0000"
  }
}

User registrations

Getting a specific user registration

Endpoint

GET https://www.my-catalog.edu/api/v1/user_registrations/:id

Parameters

Name Description
id Canvas user ID

Request

Route

GET https://www.my-catalog.edu/api/v1/user_registrations/3

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
canvas_user_id Canvas user ID Integer
name Full name String
email E-mail address String
custom_fields Custom field values, e.g. { 'phone': '(999) 123-4567' } Object
created_at Date/time registration was recorded Datetime
updated_at Date/time last updated Datetime
catalog[id] Id for the catalog this user registered for Integer
catalog[name] Name for the catalog this user registered for String

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: RtuPi55Pk81YGsO6eHl278wWJG6MAJhTdVwl1rwB9vJXtxEzmzxmWnvCEE4B8DHTzJT/8bFRCnaG4kANrhESxA==
ETag: W/"ec81397226bc5371161650931f528896"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=UzhsKzk4V0h1UjlZYk5iZlNBN01tMWNpbjUycExFQlFZTUxVYXBueDNKVStBR2FsbzFBN282MGRBdEJ3bm9PcXpmdGVNeEdrR2dMbE5vMGoyREdpVWM5ZkxCMFhaYlBlekloTXU4WXRkM0NEWWxCRU10WXliRDNEUDFER3lVOUFsazZ1VC9BekVGWkxoRStwbVZrMG9NVUwyS2N1QXNTMEZac1FmbWQrdDNRRFlWWHpKMXJVLzN5WDNCcnpHN2FyLS1iMko5SXFDUG5jbGtvc1JpWitScWlBPT0%3D--9fcc79bbfdd2014050e5a831e3969a87b1c3060f; path=/; HttpOnly
X-Request-Id: e539e6ac-d936-4c2c-92a5-cc851e37c8bf
X-Runtime: 0.089114
Content-Length: 293

Body

{
  "user_registration": {
    "canvas_user_id": 3,
    "catalog": {
      "id": 16,
      "name": "Domain Account 16"
    },
    "name": "User 3",
    "email": "user3@example.com",
    "custom_fields": {
      "favorite_color": "#BADA55",
      "code_of_conduct": "1",
      "age": "19"
    },
    "created_at": "2020/03/17 19:48:17 +0000",
    "updated_at": "2020/03/17 19:48:17 +0000"
  }
}

Listing user registrations

Endpoint

GET https://www.my-catalog.edu/api/v1/user_registrations

Parameters

Name Description
from Earliest date/time to return (optional, String). Suggested format YYYY-MM-DDTHH:MM:SSZ, e.g. 2018-01-01T00:00:00Z. System time zone is UTC.
to Latest date/time to return (optional, String). See 'from' above for format.

Request

Route

GET https://www.my-catalog.edu/api/v1/user_registrations

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: MeVENECWSNrm61CjyMn26mbdm2emW0LmxkcDI4msjkBsRR5UbLsqaym/LVpslPoLLLTRs8gMmYcK6alFLDORUg==
ETag: W/"14c78c3e2e4522a14817e18e4df78f06"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=Z2F2cDk4c0lQaUFwdXhqY3BuQ1U5d2NNbUE1SEpoT2t4ZS9rNGpSaGdHQno0SHBVaW1Kd0x6VzYzZ1Y2RW0rK09obTlJQnMwMnZxQVFxSEs4Y1BqNHVKMHpGdlNwRExRbmcvUVIwQmZxdGowZXI2WFdoZ0xmazJLVW9acVBrNS9KTlJmTXJCTE9WbTl2bXR5QjlqNFRSWCtxZ1IzRFF5RENITVZmMFlHSy9Fd3pSd3VQdmd4K1dnVjN2NjRzY3ZtLS0wS0ZWdkxPQWxnb0tlUHBCdzNKbXB3PT0%3D--1d899aee641577eb778c7b51cdcc04a38a48ac48; path=/; HttpOnly
X-Request-Id: 9e67f7de-9251-48e9-a309-79f19c7539f4
X-Runtime: 0.047810
Content-Length: 296

Body

{
  "user_registrations": [
    {
      "canvas_user_id": 1,
      "catalog": {
        "id": 14,
        "name": "Domain Account 14"
      },
      "name": "User 1",
      "email": "user1@example.com",
      "custom_fields": {
        "favorite_color": "#BADA55",
        "code_of_conduct": "1",
        "age": "19"
      },
      "created_at": "2020/03/17 19:48:16 +0000",
      "updated_at": "2020/03/17 19:48:16 +0000"
    }
  ]
}

Registering a user

Endpoint

POST https://www.my-catalog.edu/api/v1/user_registrations

Parameters

Name Description
name Full name
email E-mail address (will also serve as login)
catalog_id ID of subcatalog to associate with user (optional)
custom_fields Hash of custom field values, e.g. { 'phone': '867-5309' } (optional)

Request

Route

POST https://www.my-catalog.edu/api/v1/user_registrations

Headers

Authorization: Token token="my-token"
Content-Type: application/json
Host: www.my-catalog.edu
Cookie: 

Body

{
  "user_registration": {
    "name": "Barack Obama",
    "email": "barack@obama.com",
    "custom_fields": {
      "phone": "(999) 123-4567"
    }
  }
}

Response

Response fields

Name Description Type
canvas_user_id Canvas user ID Integer
name Full name String
email E-mail address String
custom_fields Custom field values, e.g. { 'phone': '(999) 123-4567' } Object
created_at Date/time registration was recorded Datetime
updated_at Date/time last updated Datetime
catalog[id] Id for the catalog this user registered for Integer
catalog[name] Name for the catalog this user registered for String

Status

201

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: CJVpqzirV1n3pbactprGif+qehqmYC34yQozbj4Y4UL1NTL4aAI2aSKvWrSrpWsnUq59lfANKoPumoHM7/jq5A==
ETag: W/"16d85d77517bc5de9380c1c4bee5747b"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=dGFheE9hd3NGN0Qrb0MvVUcrRytLZ3RxSjZvZHhTRFdzWUMwaUhmcEJGbzZackVmMnQwczJIdWtwSFVIeVI1bnFoMkFvTHExaDJKYUdGa29hSmZXMHc2ZUt2Mks5cS8vUmI0NkZoWm4wL3ZUMVppK0dYY1FDTWxMcHVmWEZVSlF0ODBPWDI2WS9pZDZIY1lJM211QlRZWU00ZkpHdk5PSVNJL0kxMXBqdGV0YWVHbXdjM2VabkROL3dwQitlM1hDLS1penYyYmhhY3ZXL2NwTXZaczh2MXBnPT0%3D--75fda93f039ac216bcf8a9b44599ba313299028f; path=/; HttpOnly
X-Request-Id: 64d6e0cc-2c69-41c3-b656-0a1251d840c5
X-Runtime: 0.338803
Content-Length: 242

Body

{
  "user_registration": {
    "canvas_user_id": 1234,
    "catalog": {
      "id": 15,
      "name": "Domain Account 15"
    },
    "name": "Barack Obama",
    "email": "barack@obama.com",
    "custom_fields": {
    },
    "created_at": "2020/03/17 19:48:16 +0000",
    "updated_at": "2020/03/17 19:48:16 +0000"
  }
}

Waitlist applicants

Getting a specific applicant record

Endpoint

GET https://www.my-catalog.edu/api/v1/applicants/:id

Request

Route

GET https://www.my-catalog.edu/api/v1/applicants/1

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Response fields

Name Description Type
id Identifier for this applicant Integer
listing[id] Identifier for listing Integer
listing[title] Listing title String
user[id] User ID Integer
user[name] Full name String
user[email] E-mail address String
status Status (waitlist, accepted, expired, or error) String
notified_of_opening_at Time user was notified of opening Datetime
created_at The creation date for the applicant Datetime
updated_at The last time the applicant was updated Datetime

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-CSRF-Token: sP3rZZCk4V0TM8NAuGna01nG47hViq4nprjYrYTPn2DqEL1tUmIezC7ITvnMPrZb+mUx0wpvX2y6j/cb81HxKg==
ETag: W/"dcf8ba0afb58b8e0b8f4f42e35aba91f"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=MkdqSFNqRDY2ZVJsTTRXMHl6TE51d2xKNlBIRndRbWU1ZldpWHBITEFLbnByNEU5ZGgyTXpOaWlSTHhQTlRPYmRhaGlIcS9qcll1cS9tU1ZiaWdvQVV0RDJkdnV2TUtRQmF4ZVdrTkdwUWZpRElacW1IeEVFZVZ4SFUxT3JRQkJOQ25FRlgyRE5IYkwwbnJpWU5LV1BYUnl1MzB1SklZckRVZ044ZUZHNlRhOGt5clZzYVMrMWlldVhCV1llSWROLS0wUnJoZUxZRlAvMHVQY0FoWCs2aTJBPT0%3D--43d46621068bf8f7f865fd356533e193bf84dfe0; path=/; HttpOnly
X-Request-Id: 837e97c3-1b1a-4697-bfb3-326ed46fb5be
X-Runtime: 0.044954
Content-Length: 255

Body

{
  "applicant": {
    "id": 1,
    "user": {
      "id": 1,
      "name": "Applicant",
      "email": "plz@letmein.com"
    },
    "listing": {
      "id": 29,
      "title": "Course 28"
    },
    "notified_of_opening_at": null,
    "status": "waitlist",
    "created_at": "2020/03/17 19:48:17 +0000",
    "updated_at": "2020/03/17 19:48:17 +0000"
  }
}

Listing applicants

Endpoint

GET https://www.my-catalog.edu/api/v1/applicants

Parameters

Name Description
listing_id Only include applicants for the specified listing (optional, Integer)
status Only include applicants for the specified status (optional, String)

Request

Route

GET https://www.my-catalog.edu/api/v1/applicants

Headers

Authorization: Token token="my-token"
Host: www.my-catalog.edu
Cookie: 

Response

Status

200

Headers

X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Per-Page: 20
Total: 1
Content-Type: application/json; charset=utf-8
X-CSRF-Token: oxf3O/onE4qW2bjevCniL7TFIo2IODzmSCVDVV7NR8eHNPYyFqJL1zgKzkDcb4IZZuc4KrwVsyFWMh7sCEQL2Q==
ETag: W/"13360e7b2c02883da7fd6053eaa926cb"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _gallery_session=YzdJREZYd2VZSlBWVi9hdU4ram5TY3A2SHl0bTJWdVVGVE9Ka2FpUXVUSVFlK2hTRlhPY1hWcW5oMnM3SFRFQjlpNzV5TmxqanE0Y0E3K3NBYWJjQXdNZGE3SHlWMG5xMDQ1Z0YvUnVFTHNTQ0hRcjNVTWsySFBXVnU5cjRCQVNoTXQxUC9nRHNBUTltc0VVREFRZHhzenUrdVJjRDIzYUE5Nzl6MXZjaXNxMmJXa2lXc056NHpWV0xUV2FyaWRKLS1hTTNOeUhlQmJ5OVlPRDZOWjlXc2ZBPT0%3D--9ac3cead65ea90a9350d222571782ca2a7a0dbe1; path=/; HttpOnly
X-Request-Id: 0f7a7401-523a-4f74-b94d-936228e2c826
X-Runtime: 0.041693
Content-Length: 258

Body

{
  "applicants": [
    {
      "id": 2,
      "user": {
        "id": 2,
        "name": "Applicant",
        "email": "plz@letmein.com"
      },
      "listing": {
        "id": 30,
        "title": "Course 29"
      },
      "notified_of_opening_at": null,
      "status": "waitlist",
      "created_at": "2020/03/17 19:48:17 +0000",
      "updated_at": "2020/03/17 19:48:17 +0000"
    }
  ]
}