To enroll customers to a program at Climate use our /v5/enrollments API. Currently we allow enrollments by program and by location. Before we get started, partners should have a set of credentials with the correct scopes:

• enrollment:read
• enrollment:write
• experiments:read
• experiments:write
• parties:read

Follow our OAuth2 documentation for detailed information on getting a token here.

These are the parameters necessary to create an enrollment by program:

• x-enrollment-type: program
• experimentProtocolId - this uuid will be given to you by Climate
• temporalEntity
  • dimensionality: INDIVIDUAL
    • id: this uuid will be given to you by Climate
    • temporalPeriodTypeName: AgronomicSeason, LocalAgronomicSeason LocalCropSeason, or GrowingSeason
  • dimensionality: INTERVAL
    • startId: this uuid will be given to you by Climate
    • endId: this uuid will be given to you by Climate
    • temporalPeriodTypeName: AgronomicSeason, LocalAgronomicSeason LocalCropSeason, or GrowingSeason

Here is a request for dimensionality INDIVIDUAL:

POST /v5/enrollments HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token
Content-Type: application/json

{
  "experimentProtocolId": "9030e693-e76b-40e8-b53a-dfc03ab20cfc",
  "temporalEntity": {
    "dimensionality": "INDIVIDUAL",
    "id": "c06e18a3-dbc2-43a4-8119-a2778c63e19d",
    "temporalPeriodTypeName": "GrowingSeason"
  }
}

Here is a request for dimensionality INTERVAL:

POST /v5/enrollments HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token
Content-Type: application/json

{
  "experimentProtocolId": "9030e693-e76b-40e8-b53a-dfc03ab20cfc",
  "temporalEntity": {
    "dimensionality": "INTERVAL",
    "startId": "6f97a3f0-3cd8-4458-a793-82906805e1b9",
    "endId": "25e56586-77b7-41aa-9362-e9cf39778340",
    "temporalPeriodTypeName": "GrowingSeason"
  }
}

The response will have the enrollmentId required to get individual enrollments and update enrollments.

201 Created
{
  "id": "aed9b169-7c25-4e94-a632-3d507b769ab7",
  "createdAt": "2022-10-03T16:49:27.07",
  "dataLegitimacy": "LEGITIMATE",
  "enrollmentStatus": "APPROVED",
  "experimentProtocolId": "9030e693-e76b-40e8-b53a-dfc03ab20cfc",
  "itemStatus": "ACTIVE",
  "temporalEntity": {
    "id": "c06e18a3-dbc2-43a4-8119-a2778c63e19d",
    "dimensionality": "INDIVIDUAL",
    "temporalPeriodTypeName": "GrowingSeason"
  },
  "updatedAt": "2022-10-03T16:49:27.07"
}

ExperimentId is a required parameter and you can get it by making a GET request to /v5/experiments with the experimentEnrollmentId query parameter which will be given to you by Climate.

Example GET experiments request:

GET /v5/experiments?experimentEnrollmentId=4b1a6ef3-a81c-4406-b58f-6ad2f5bf9f96 HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
Authorization: Bearer token

Example GET experiments response:

200 OK
{
  "results": [
    {
      "createdAt": "2022-09-07T12:58:37.265",
      "dataLegitimacy": "LEGITIMATE",
      "experimentEnrollmentId": "4b1a6ef3-a81c-4406-b58f-6ad2f5bf9f96",
      "id": "5a73807f-9ea2-4cb8-b93a-d11a8ba99856",
      "experimentStatus": "INITIATED",
      "name": "TEST experiment",
      "temporalEntity": {
        "id": "29953bbd-2558-46db-831a-ec0a72d3762f",
        "dimensionality": "INDIVIDUAL",
        "temporalPeriodTypeName": "GrowingSeason"
      },
      "updatedAt": "2022-09-07T12:58:37.265",
      "itemStatus": "ACTIVE"
    }
  ]
}

If the results is an empty array then you can create an experiment.

POST experiments example:

POST /v5/experiments HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
Authorization: Bearer token

{
  "experimentEnrollmentId": "4b1a6ef3-a81c-4406-b58f-6ad2f5bf9f96",
  "name": "Test experiment",
  "temporalEntity": {
    "id": "29953bbd-2558-46db-831a-ec0a72d3762f",
    "dimensionality": "INDIVIDUAL",
    "temporalPeriodTypeName": "GrowingSeason"
  }
}

The id in the response will be the required experimentId parameter for the POST enrollments by location.

These are the parameters necessary to create an enrollment by location:

• x-enrollment-type: location
• experimentId: this is the uuid from the experiments request
• experimentLocationStatus:
  • NOMINATED - The location has been identified and proposed for use in the experiment
  • QUALIFIED - The location has complied with the protocol or otherwise met the criteria for inclusion in the experiment
  • RECOMMENDED - The location has been qualified and presented to the experimenter as a candidate for selection
  • SELECTED - The location has been approved and accepted by all parties for use in the experiment
  • ELIMINATED - The location has been rejected for use in the experiment
  • CLOSED - The location is not taking part in any ongoing experiments
• locationId: this is the field uuid from the fields request
• temporalEntity
  • dimensionality: INDIVIDUAL
    • id: this uuid will be given to you by Climate
    • temporalPeriodTypeName: AgronomicSeason, LocalAgronomicSeason LocalCropSeason, or GrowingSeason
  • dimensionality: INTERVAL
    • startId: this uuid will be given to you by Climate
    • endId: this uuid will be given to you by Climate
    • temporalPeriodTypeName: AgronomicSeason, LocalAgronomicSeason LocalCropSeason, or GrowingSeason

Here is a request for dimensionality INDIVIDUAL:

POST /v5/enrollments HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: location
Authorization: Bearer token
Content-Type: application/json

Here is a request for dimensionality INTERVAL:

POST /v5/enrollments HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: location
Authorization: Bearer token
Content-Type: application/json

{
  "experimentId":"5a73807f-9ea2-4cb8-b93a-d11a8ba99856",
  "experimentLocationStatus":"NOMINATED",
  "locationId":"c79883c7-d3b5-4a39-add3-d9e9fb861577",
  "temporalEntity": {
    "dimensionality": "INTERVAL",
    "startId": "6f97a3f0-3cd8-4458-a793-82906805e1b9",
    "endId": "25e56586-77b7-41aa-9362-e9cf39778340",
    "temporalPeriodTypeName": "GrowingSeason"
  }
}

After an enrollment is created, you will be able to retrieve the enrollments with the enrollments id.

Get enrollments by program:

GET /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token

Get enrollments by location:

GET /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
x-enrollment-type: location
Authorization: Bearer token

For updating a program, the enrollment id is required. The new experimentProtocolId and/or temporalEntity id are also required.

Below is an update enrollments with dimensionality INDIVIDUAL:

PUT /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token
Content-Type: application/json

{
  "experimentProtocolId": "9030e693-e76b-40e8-b53a-dfc03ab20cfc",
  "temporalEntity": {
    "id": "c06e18a3-dbc2-43a4-8119-a2778c63e19d",
    "dimensionality": "INDIVIDUAL",
    "temporalPeriodTypeName": "GrowingSeason"
  }
}

Below is an update enrollments with dimensionality INTERVAL:

PUT /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token
Content-Type: application/json

{
  "experimentProtocolId": "9030e693-e76b-40e8-b53a-dfc03ab20cfc",
  "temporalEntity": {
    "dimensionality": "INTERVAL",
    "startId": "6f97a3f0-3cd8-4458-a793-82906805e1b9",
    "endId": "25e56586-77b7-41aa-9362-e9cf39778340",
  "temporalPeriodTypeName": "GrowingSeason"
  }
}

For updating a location, the enrollment id is required. The new experimentId and/or locationId and/or temporalEntity id are also required.

Below is an update enrollments with dimensionality INDIVIDUAL:

PUT /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
x-api-key: api-key
x-enrollment-type: location
Authorization: Bearer token
Content-Type: application/json

After an enrollment is created, you will be able to remove the enrollments with the enrollments id.

Remove enrollments by program:

DELETE /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
x-enrollment-type: program
Authorization: Bearer token

Remove enrollments by location:

DELETE /v5/enrollments/f122289e-28fb-47fc-970a-e3f05ce0ed42 HTTP/1.1
Host: platform.climate.com
Accept: application/json
Content-Type: application/json
x-api-key: api-key
x-enrollment-type: location
Authorization: Bearer token