Integration Documentation

curl -X POST https://api-prod.dietid.com/api/v3/sso
   -H 'Content-Type: application/json'
   -H "Accept: application/json"
   -H "Authorization: Bearer {clientSecret}"
   -H "X-DietID-PartnerUserId: abc123"
   -H "X-DietID-ClientId: {clientToken}"
   -d '{
        "partnerUserId": "abc123",
        "email": "example@dietid.com",
        "firstName": "NameTest",
        "lastName": "LastNameTest",
        "healthGoals" : ["ControlBloodPressure"],
        "additionalParams": { "hello": "world" },
        "patientAlert": "This is a provider provided alert",
        "height": 85,
        "weight": 123,
        "age": 45,
        "parentalConsentGiven": true,
        "DOB": "1999-11-12",
        "postalCode": "90210",
        "gender": "Male",
        "desiredUsername": "desired_username_123",
        "activityLevel": "HighlyActive"
}'

curl https://api-staging.dietid.com/api/v3/diets
   -H "Accept: application/json"
   -H "Authorization: Bearer {userToken || clientSecret}"

POST '/api/v1/sso'
GET '/api/v1/firehose/users/partnerUserId/:partner_user_id'
GET '/api/v1/firehose/users/:user_id'

POST '/api/v3/sso'

GET '/api/v3/goals'
GET '/api/v3/goals/all'
GET '/api/v3/goals/:slug'

GET '/api/v3/diets'
GET '/api/v3/diets/all'
GET '/api/v3/diets/:diet_code'
GET '/api/v3/diets/:diet_code/:quality'
GET '/api/v3/diets/compare/:diet_code/:quality/:ideal_code/:ideal_quality'

'?view=nosidebar'

'?view=nosidebar,noprogressbar'

import { Opaque as _Opaque } from 'type-fest'

export type Opaque<Type, Token = unknown> = _Opaque<Type, Token>

/**
 * Screener questions that are not shown to the user are sent as null.
 */
export type ScreenerResponse = 'Yes' | 'No' | 'Sometimes' | null

/**
 * If during the screener the user indicates that they consume meat and grains
 * then they are also asked if they follow a particular style of diet. Otherwise this value is null.
 * The string type is only necessary for when the user specifies a style other than what's listed.
 * Free text responses to "Other ethnic style" and "Other pattern" are sent as "OtherEthnic:foo" and
 * "OtherPattern:foo" respectively where foo is what the user typed in the textbox.
 */
export type StyleScreenerResponse = 'None' | 'LOC' | 'LOF' | 'MED' | 'MEX' | 'SOU' | string | null

export type Gender = 'Male' | 'Female' | 'NonBinary' | 'PreferToSelfDescribe' | 'PreferNotToAnswer'

export type WeightTrend = 'Rising' | 'Constant' | 'Falling'

export type ActivityLevel = 'Sedentary' | 'BelowGuidelines' | 'MeetsGuidelines' | 'AboveGuidelines' | 'HighlyActive'

export type DietRestriction =
  | 'DairyFree'
  | 'NutFree'
  | 'GlutenFree'
  | 'WheatFree'
  | 'ShellfishFree'
  | 'SoyFree'
  | 'PeanutFree'
  | 'AlcoholFree'
  | 'EggFree'
  | 'Halal'
  | 'Kosher'
  | 'Organic'

/**
 * The string type is only necessary for when the user specifies a goal other than what's listed.
 * "Other" goals are sent as "other:foo" where foo is what the user typed in the textbox.
 */
export type HealthGoal =
  | 'ReduceCardioRisk'
  | 'ControlBloodPressure'
  | 'PreventOrControlDiabetes'
  | 'ManageHeartFailure'
  | 'DecreaseInflammation'
  | 'ImproveOverall'
  | 'ManageWeight'
  | 'ManageHighCholesterol'
  | 'ManageFoodSensitivities'
  | 'ImproveGutHealth'
  | string

export type WeightGoal = 'Lose' | 'Maintain' | 'Gain'

export type NutrientUnit = 'g' | 'mg' | 'mcg' | '%' | 'kcal'

import { Opaque } from '../types'

export interface Challenge {
  id: Opaque<number, 'Challenge'>

  /**
   * The name of the challenge.
   */
  name: string
}

import { ChallengeSubscriptionState, Opaque } from '../types'
import { Challenge } from './Challenge'
import { Checkin } from './Checkin'
import { Tip } from './Tip'
import { User } from './User'

export interface ChallengeSubscription {
  id: Opaque<number, 'ChallengeSubscription'>

  /**
   * The user the challenge subscription belongs to.
   */
  userId: User['id']

  /**
   * The challenge the challenge subscription belongs to.
   */
  challengeId: Challenge['id']

  /**
   * @todo Add description
   */
  day: any

  /**
   * A helpful tip for the user to complete the challenge.
   */
  tip: Tip | null

  /**
   * The number of times the user should check in throughout the day.
   * For example, a "drink 8 glasses of water" challenge may be 8.
   */
  checkinsPerDay: number

  /**
   * The challenge subscription's state. Valid transitions are:
   *
   * StartingTomorrow -> Active
   *
   * Active -> MissedYesterday | Failed | Succeeded
   *
   * Failed -> StartingTomorrow | Active
   */
  state: ChallengeSubscriptionState

  /**
   * Past checkins the user has made for the challenge subscription.
   */
  checkins: Checkin[]
}

import { Opaque } from '../types'
import { ChallengeSubscription } from './ChallengeSubscription'

export interface Checkin {
  id: Opaque<number, 'Checkin'>

  /**
   * The challenge subscription this checkin is for.
   */
  challengeSubscriptionId: ChallengeSubscription['id']

  /**
   * Arbitrary additional data passed to Diet ID when the user checked in.
   */
  data: object | null
}

import { Opaque } from '../types'

export interface Diet {
  id: Opaque<number, 'Diet'>

  /**
   * Human-readable label for the diet type (e.g., "American").
   */
  name: string

  /**
   * Unique code for the diet type (e.g., "AME")
   */
  code: string

  /**
   * The quality of the diet on a scale of 1 to 10 (e.g., 5).
   */
  quality: number

  /**
   * Human-readable label for the diet type and quality (e.g., "American quality 7 (7 out of 10)")
   */
  longName: string

  /**
   * A short sentence describing the diet (e.g., "American Quality 5 (Q5) is characterized by fresh and processed meat, ...")
   */
  description: string

  /**
   * The Healthy Eating Index (HEI) of the diet.
   */
  hei: number

  /**
   * A photo of the diet's typical food and drink.
   */
  fingerprintPhotoUrl: string

  /**
   * @todo Add description
   */
  foodGroupValues: { [foodGroupId: string]: number }

  /**
   * Url to a PDF of a mealplan
   */
  mealPlanUrl: string
}

import { Opaque } from '../types'
import { NutrientUnit } from '../types'

export interface NutritionInfo {
  /**
   * Unique identifier (e.g., "added-sugars-by-total-sugars")
   */
  key: Opaque<string, 'NutritionInfo'>

  /**
   * Quantitative value (e.g., 60.06351427805127)
   */
  value: number

  /**
   * Value's unit of measurement (e.g., "g")
   */
  unit: NutrientUnit

  /**
   * Human-readable label for display of the value and unit (e.g., "Added Sugars")
   */
  label: string

  /**
   * @todo Add description
   */
  isDefault: boolean
}

import { Opaque } from '../types'

export interface Tip {
  id: Opaque<number, 'Tip'>

  /**
   * The content of the tip.
   */
  content: string
}

import { Opaque } from '../types'
import { Challenge } from './Challenge'
import { ChallengeSubscription } from './ChallengeSubscription'
import { Workflow } from './Workflow'

/**
 * A user identifier provided by you, the partner
 */
export type PartnerUserID = Opaque<string, 'PartnerUserID'>

export interface User {
  /**
   * The user's unique identifier within Diet ID's system (assigned by Diet ID).
   */
  id: Opaque<number, 'User'>

  /**
   * The user's unique identifier within a partner system (assigned by you).
   */
  partnerUserId: PartnerUserID | null

  /**
   * The record of the assessment the user took to determine their ID diet.
   */
  dietIdWorkflowId: Workflow['id'] | null

  /**
   * The record of the assessment the user took to determine their Ideal diet.
   */
  dietIdealWorkflowId: Workflow['id'] | null

  /**
   * The challenge the user is currently participating in.
   */
  challenge: Challenge | null

  /**
   * The join record between the user and their current challenge, which contains additional info specific to that user.
   */
  challengeSubscription: ChallengeSubscription | null
}

import {
  ActivityLevel,
  DietRestriction,
  Gender,
  HealthGoal,
  Opaque,
  ScreenerResponse,
  StyleScreenerResponse,
  WeightGoal,
  WeightTrend
} from '../types'
import { Challenge } from './Challenge'
import { Diet } from './Diet'
import { NutritionInfo } from './NutritionInfo'
import { User } from './User'

/**
 * A workflow identifier provided by you, the partner
 */
export type PartnerWorkflowID = Opaque<string, 'PartnerWorkflowID'>

export interface Workflow {
  id: Opaque<number, 'Workflow'>

  /**
   * The workflow's unique identifier within a partner system (assigned by you).
   */
  partnerWorkflowId: PartnerWorkflowID | null

  /**
   * The user the workflow belongs to.
   */
  userId: User['id']

  /**
   * A private url to view the workflow results.
   */
  shareUrl: string

  /**
   * Basic demographic and lifestyle info
   */
  userInfo?: {
    gender: Gender
    ageInYears: number
    weightInPounds: number
    heightInInches: number
    weightTrend: WeightTrend
    activityLevel: ActivityLevel
  }

  /**
   * Diet screeners describe what a user currently does and does not eat.
   * Note: Many of these will be null since we ask the user one screener question
   * at a time and often skip a number of them based on branching logic.
   */
  dietScreener: {
    meat: ScreenerResponse
    poultry: ScreenerResponse
    fish: ScreenerResponse
    grains: ScreenerResponse
    dairy: ScreenerResponse
    style: StyleScreenerResponse
  }

  /**
   * Diet restrictions are what a user cannot eat due to allergies, religious observance, etc.
   */
  dietRestrictions: DietRestriction[]

  /**
   * Ideal goals are selected by the user to help determine what ideal diets are optimal for their needs.
   */
  idealGoals: {
    /**
     * Health goals are specific things the user wants to accomplish with their change in diet.
     */
    forHealth: HealthGoal[]

    /**
     * A weight goal qualifies the "ManageWeight" health goal (whether to lose, maintain, or gain weight)
     */
    weightGoal: WeightGoal | null

    /**
     * The goal diet is a diet the user specifically wants to move towards apart from any health goals.
     */
    goalDiet: Diet['code'] | null
  }

  /**
   * The user's ID diet as determined by the assessment.
   */
  dietId: Diet | null

  /**
   * The user's Ideal diet as determined by the assessment.
   */
  dietIdeal: Diet | null

  /**
   * Nutrition info for the user's ID diet.
   * This is workflow-specific data, with baseline diet nutrients adjusted for height, weight, etc.
   */
  dietIdNutritionInfo: NutritionInfo[] | null

  /**
   * Nutrition info for the user's Ideal diet.
   * This is workflow-specific data, with baseline diet nutrients adjusted for height, weight, etc.
   */
  dietIdealNutritionInfo: NutritionInfo[] | null

  /**
   * The sequence of challenges a user is pre-determined to complete based on their ID and Ideal diets.
   */
  challengeIds?: Challenge['id'][]

  /**
   * Whether the workflow has been completed or is a work in progress.
   */
  completed: boolean

  /**
   * The UTC datetime when the workflow was started.
   */
  createdAt: Date
}

export * from './Challenge'
export * from './ChallengeSubscription'
export * from './Checkin'
export * from './Diet'
export * from './NutritionInfo'
export * from './Tip'
export * from './User'
export * from './Workflow'

import { request } from './util'
import { Challenge, ChallengeSubscription } from '../models'

export interface CreateChallengeSubscriptionBody {
  challengeSubscription: {
    challengeId: Challenge['id']
    startTomorrow: boolean
  }
}

export type CreateChallengeSubscriptionResponse =
  | { success: false; message: string }
  | { success: true; challengeSubscription: ChallengeSubscription }

/**
 * Starts a user on a new challenge, creating a challenge subscription.
 *
 * @param userId The identifier assigned by Diet ID for the user.
 * @param challengeId The identifier assigned by Diet ID for the challenge.
 * @param startTomorrow (optional) Whether the user should start the challenge tomorrow instead of today (default: false).
 *
 * @returns The challenge subscription (join record between user and challenge).
 */
export const createChallengeSubscription = async (
  challengeId: CreateChallengeSubscriptionBody['challengeSubscription']['challengeId'],
  startTomorrow: CreateChallengeSubscriptionBody['challengeSubscription']['startTomorrow'] = false
) =>
  request<CreateChallengeSubscriptionResponse>('POST', '/api/v2/challenge_subscriptions', {
    challengeSubscription: { challengeId, startTomorrow }
  })

import { request } from './util'
import { ChallengeSubscription, Checkin } from '../models'

export interface CreateCheckinBody {
  checkin: {
    challengeSubscriptionId: ChallengeSubscription['id']
    successful: boolean
    forYesterday: boolean
    metadata?: object
  }
}

export type CreateCheckinResponse = { success: false; message: string } | { success: true; checkin: Checkin }

/**
 * Check in a user for a particular challenge.
 *
 * @param challengeSubscriptionId The id of the challenge subscription the user is checking in for.
 * @param successful Whether the user indicated success or failure in the checkin.
 * @param forYesterday (optional) Whether the checkin is for yesterday instead of today (default: false).
 * @param metadata (optional) Arbitrary additional data you'd like to attach to the checkin.
 *
 * @returns The checkin record.
 */
export const createCheckin = (
  challengeSubscriptionId: CreateCheckinBody['checkin']['challengeSubscriptionId'],
  successful: CreateCheckinBody['checkin']['successful'],
  forYesterday: CreateCheckinBody['checkin']['forYesterday'] = false,
  metadata?: CreateCheckinBody['checkin']['metadata']
) =>
  request<CreateCheckinResponse>('POST', '/api/v2/checkins', {
    checkin: {
      challengeSubscriptionId,
      successful,
      forYesterday,
      metadata
    }
  })

import { request } from './util'
import { CreateUserBody } from './createUser'

export interface CreateSSOBody {
  user: {
    /**
     * The user's unique identifier within a partner system (assigned by you).
     */
    partnerUserId: User['partnerUserId']

    /**
     * The user's email address.
     */
    email?: string

    /**
     * The user's first name.
     */
    firstName?: string

    /**
     * The user's last name.
     */
    lastName?: string

    /**
     * The user's desired username (optional).
     */
    desiredUsername?: string

    /**
     * The user's gender (optional).
     */
    gender?: enum:Gender

    /**
     * The user's postal code (optional).
     */
    postalCode?: string

    /**
     * The user's date of birth formatted as YYYY-MM-DD (optional).
       - 1999-11-12
     */
    DOB?: string

    /**
     * The user's age in years (optional).
     */
    age?: integer

    /**
     * The user's height in inches (optional).
     */
    height?: integer

    /**
     * The user's weight in lbs (optional).
     */
    weight?: integer

    /**
     * The user's activity level (optional).
     */
    activityLevel?: enum:ActivityLevel

    /**
     * The user's pre-defined health goals (optional).
     */
    healthGoals?: array:HealthGoal

    /**
     * The user's initial patient alert (optional).
     */
    patientAlert?: string

    /**
     * The user's initial patient alert (optional).
     */
    parentalConsentGiven?: bool

    /**
     * Any addditional user params (optional).
     */
    additionalParams?: string - JSON blob

  }

export type CreateSSOResponse = { success: false; message: string } | { success: true; url: string }

/**
 * Returns a url the frontend can use to embed a Diet ID assessment in an iframe, webview, etc.
 * The user is automatically signed in and prompted to complete the assessment.
 *
 * @param user The fields for finding or creating a Diet ID user (id required; email, firstName, and lastName optional)
 * @returns A url that signs in a user and prompts them to complete an assessment.
 *
 */
export const createSSO = (user: CreateSSOBody['user']) => request<CreateSSOResponse>('POST', '/api/v3/sso', { user })

import { request } from './util'
import { CreateUserBody } from './createUser'

export type CreateSSOBody = CreateUserBody

export type CreateSSOResponse = { success: false; message: string } | { success: true; url: string }

/**
 * Returns a url the frontend can use to embed a Diet ID assessment in an iframe, webview, etc.
 * The user is automatically signed in and prompted to complete the assessment.
 *
 * @param user The fields for finding or creating a Diet ID user (id required; email, firstName, and lastName optional)
 * @returns A url that signs in a user and prompts them to complete an assessment.
 *
 */
export const createSSO = (user: CreateSSOBody['user']) => request<CreateSSOResponse>('POST', '/api/v1/sso', { user })

import { request } from './util'
import { User } from '../models'

export interface CreateUserBody {
  user: {
    /**
     * The user's unique identifier within a partner system (assigned by you).
     */
    partnerUserId: User['partnerUserId']

    /**
     * The user's email address.
     */
    email?: string

    /**
     * The user's first name.
     */
    firstName?: string

    /**
     * The user's last name.
     */
    lastName?: string
  }
}

export type CreateUserResponse = { success: false; message: string } | { success: true; user: User }

/**
 * Creates a corresponding Diet ID user for a local user.
 *
 * @param user The required fields for creating a Diet ID user (id, email, first name, last name)
 *
 * @returns The newly created Diet ID user.
 */
export const createUser = async (user: CreateUserBody['user']) =>
  request<CreateUserResponse>('POST', '/api/v2/users', { user })

import { request } from './util'
import { User } from '../models'

export type GetCurrentUserResponse = { success: false; message: string } | { success: true; user: User | null }

/**
 * Returns the current Diet ID user.
 *
 * @returns The Diet ID user record.
 */
export const getCurrentUser = async () => request<GetCurrentUserResponse>('GET', '/api/v2/user')

import { request } from './util'
import { Workflow } from '../models'

export interface GetWorkflowParams {
  workflowId: Workflow['id']
}

export type GetWorkflowResponse =
  | {
      success: false
      message: string
    }
  | { success: true; workflow: Workflow }

/**
 * Returns the data collected and results from an assessment (workflow).
 *
 * @param workflowId The identifier assigned by Diet ID for the workflow.
 *
 * @returns The workflow with the id.
 */
export const getWorkflow = (workflowId: GetWorkflowParams['workflowId']) =>
  request<GetWorkflowResponse>('GET', `/api/v2/workflows/${workflowId}`)

let gateway = 'http://localhost:3500'

/**
 * Sets the url to the API Gateway all requests should route through.
 *
 * @param url The url to your API Gateway. e.g., https://yourapiserver.com/pathtodietidgateway
 */
export const setGateway = (url: string) => {
  gateway = url
}

/**
 * Possible HTTP verbs within Diet ID's API.
 */
type RequestMethod = 'GET' | 'POST'

/**
 * Utility method for sending API requests to Diet ID.
 *
 * @param method The HTTP verb for the request ("GET", "POST", etc.)
 * @param endpoint The url slug for a specific portion of the API
 * @param body Optional data to be sent with POST and PUT requests
 *
 * @returns The JSON response from Diet ID for the API request.
 */
export const request = async <T>(method: RequestMethod, endpoint: string, body?: object): Promise<T> => {
  if (!gateway) {
    throw new Error("Please configure your API Gateway before making an API request (with setGateway('...'))")
  }

  const url = `${gateway}${endpoint}`
  const headers = { Accepts: 'application/json', 'Content-Type': 'application/json' }
  const data = JSON.stringify(body)

  return (await fetch(url, { headers, method, body: data })).json()
}

export * from './createChallengeSubscription'
export * from './createCheckin'
export * from './createSSO'
export * from './createUser'
export * from './getCurrentUser'
export * from './getWorkflow'
export * from './util'