> ## Documentation Index > Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt > Use this file to discover all available pages before exploring further. # Add to order > Adds the requested services to the existing ordered case. The requested services must be part of the package for the case. The authentication token must be for the group that the case is owned by. ## OpenAPI ````yaml /background-check-api/api-reference/openapi.json post /case/id/{caseId}/add/services openapi: 3.1.0 info: title: KarmaCheck API description: >- All requests to the KarmaCheck API require a JSON Web Token (JWT) in the Authorization header. For an overview of the API and its authentication method, refer to the following topics: - [API basics](docs/overview/apis/api-overview.md) - [Authentication](docs/overview/apis/authentication.md) - [Environments](docs/overview/apis/environments.md) - [Status codes and errors](docs/overview/apis/errors.md) version: '1.0' contact: name: KarmaCheck email: customersuccess@karmacheck.com servers: - description: Stage url: https://api-stage.karmacheck.io - description: Prod url: https://api.karmacheck.io security: - JWT: [] tags: - name: Authentication - name: Cases - name: Candidate onboarding - name: Secure documents - name: Packages - name: Services - name: Users - name: Companies - name: Partner integrations paths: /case/id/{caseId}/add/services: parameters: - schema: type: string name: caseId in: path required: true description: The ID of the case to add services to. post: tags: - Cases summary: Add to order description: >- Adds the requested services to the existing ordered case. The requested services must be part of the package for the case. The authentication token must be for the group that the case is owned by. operationId: post-case-id-caseId-add-services parameters: [] requestBody: content: application/json: schema: type: object x-examples: Example 1: services: - id: 85307784-1f84-471a-8596-c8ea088c3a62 orderData: - caseOrderDataTypeId: codt-education serviceId: 85307784-1f84-471a-8596-c8ea088c3a62 metadata: {} properties: services: type: array items: type: object properties: id: type: string description: >- The unique identifier of a service. See [Service](docs/reference/service.md) for a list of possible values. orderData: type: array items: $ref: '#/components/schemas/CaseOrderData' orderConfig: $ref: '#/components/schemas/OrderConfig' description: >- Updated [configurations](docs/reference/order-configuration.md) that describe how to run certain screenings for the case. The current configurations for the case can be overridden only if there has not already been a screening dispatched where that configuration applies. For example, if a criminal screening was ordered during case creation, then `aliasNameConfiguration` cannot be updated. examples: Example 1: value: services: - id: service-cplc orderData: - caseOrderDataTypeId: codt-cplc serviceId: service-cplc metadata: cplcId: 1d16c91d-c2da-47d1-b102-bd67d5b8b1ee fields: - fieldId: licenseNumber value: L1234567 - fieldId: firstName value: Matt - fieldId: lastName value: Williams - fieldId: state value: NY orderConfig: serviceConfigs: 9ac65633-b4c4-4062-875c-3556db9d2a08: verificationMethod: psv-first 85307784-1f84-471a-8596-c8ea088c3a62: verificationMethod: psv-first description: >- `services` and `orderData` are both optional, but at least one of them is required to call this endpoint. responses: '200': description: success '403': description: Unauthorized Request '422': description: >- The report is not ready yet, or a data issue such as: - The service specified is not allowed for the case. - A configuration is already set on the case for a dispatched service. '500': description: Server Error security: - JWT: [] components: schemas: CaseOrderData: title: CaseOrderData type: object description: >- The data related to a service. Each service has different `metadata` properties based on the specified `caseOrderDataTypeId`. See [Provide order data](docs/guides/order-data.md) for additional details. required: - caseOrderDataTypeId - metadata properties: caseOrderDataTypeId: type: string enum: - codt-govt-id - codt-dob - codt-current-candidate-address - codt-ohs-scheduling-address - codt-education - codt-employment - codt-mvr - codt-alias - codt-address - codt-jurisdiction-county - codt-jurisdiction-fed-district - codt-jurisdiction-state - codt-cplc - codt-shipment - codt-ohs-service-substitutions - codt-idp description: The type of data to include in the order. serviceId: type: string description: >- The ID of a [service](docs/reference/service.md) that requires a type of case order data. This field is required for the following case order data types: `codt-education` `codt-employment` `codt-mvr` `codt-alias` `codt-jurisdiction-county` `codt-jurisdiction-fed-district` `codt-jurisdiction-state` `service-cplc` `service-mask-shipment` metadata: oneOf: - $ref: '#/components/schemas/CaseOrderDataGovtID' type: object - $ref: '#/components/schemas/CaseOrderDataDOB' type: object - $ref: '#/components/schemas/CaseOrderDataCandidateAddress' type: object - $ref: '#/components/schemas/CaseOrderDataOHSAddress' type: object - $ref: '#/components/schemas/CaseOrderDataEducation' type: object - $ref: '#/components/schemas/CaseOrderDataEmployment' type: object - $ref: '#/components/schemas/CaseOrderDataMVR' type: object - $ref: '#/components/schemas/CaseOrderDataAlias' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdiction' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionCounty' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionFederal' type: object - $ref: '#/components/schemas/CaseOrderDataJurisdictionState' type: object - $ref: '#/components/schemas/CaseOrderDataCPLC' type: object - $ref: '#/components/schemas/CaseOrderDataShipment' type: object - $ref: '#/components/schemas/CaseOrderDataOHSServiceSubstitutions' - $ref: '#/components/schemas/CaseOrderDataDocumentProcessing' OrderConfig: title: OrderConfig type: object description: >- Options that describe how to run certain screenings for a case. See [Order configuration](docs/reference/order-configuration.md) for details on all configuration options. All properties are optional, but a configuration will be set for all applicable screenings on the package regardless of whether those screenings are ordered. Therefore, aside from the `contacts` object, the default configuration will be used if one is not set. properties: contacts: type: array description: A list of people to contact about the case. items: $ref: '#/components/schemas/Contact' aliasNameConfiguration: $ref: '#/components/schemas/ConfigValuesAlias' ohsDrugPassportExpirationPolicy: $ref: '#/components/schemas/ConfigValuesOhsDrugPassportExpirationPolicy' lostOrIncompleteOHSDrugPolicy: $ref: '#/components/schemas/ConfigValuesDrugPolicy' diluteDrugPolicy: $ref: '#/components/schemas/ConfigValuesDrugPolicy' serviceConfigs: type: object description: Services with configuration options. properties: 9ac65633-b4c4-4062-875c-3556db9d2a08: type: object description: The configuration for employment verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The method for verifying employment. service-employment-income: type: object description: The configuration for employment income verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEmploymentVerification' description: The method for verifying employment and income. 85307784-1f84-471a-8596-c8ea088c3a62: type: object description: The configuration for education verification. properties: verificationMethod: $ref: '#/components/schemas/ConfigValuesEducationVerification' description: The method for verifying education. service-ohs-tb-quantiferon-gold: type: object description: The configuration for Quantiferon testing. properties: substitutionPolicy: $ref: '#/components/schemas/ConfigValuesQuantiferon' description: The policy for Quantiferon testing substitution. service-ohs-tb-tspot-test: type: object description: The configuration for T-Spot testing. properties: substitutionPolicy: $ref: '#/components/schemas/ConfigValuesTspot' description: The policy for T-Spot testing substitution. CaseOrderDataGovtID: title: CaseOrderDataGovtID type: object description: The candidate data when `caseOrderDataTypeId` is `codt-govt-id`. required: - govtId properties: govtId: type: string example: 111-22-3333 description: >- The candidate's Social Security number in the format *xxx*-*xx*-*xxxx*. pattern: ^\d{3}-\d{2}-\d{4}$ CaseOrderDataDOB: title: CaseOrderDataDOB type: object description: The candidate data when `caseOrderDataTypeId` is `codt-dob`. required: - dob properties: dob: type: string example: '1986-06-26' format: date description: The candidate's date of birth in the format *YYYY*-*MM*-*DD*. CaseOrderDataCandidateAddress: title: CaseOrderDataCandidateAddress type: object description: >- The order data (candidate's current home address) when `caseOrderDataTypeId` is `codt-current-candidate-address`. examples: - address1: 6 Flagstone Drive address2: Apartment 2 city: Hudson state: NH postalCode: '03051' country: US required: - address1 - city - state - postalCode - country properties: address1: type: string description: The candidate's street address. address2: type: string description: The candidate's street address, continued. city: type: string description: The candidate's city of residence. state: type: string description: >- The two-letter abbreviation of the state in which the candidate resides. postalCode: type: string description: The candidate's zip code. country: type: string description: >- The two-letter abbreviation of the country in which the candidate resides. CaseOrderDataOHSAddress: title: CaseOrderDataOHSAddress type: object description: >- The order data (address for finding nearby clinics) when `caseOrderDataTypeId` is `codt-ohs-scheduling-address`. required: - address1 - city - state - postalCode - country properties: address1: type: string address2: type: string city: type: string state: type: string description: The two-letter state code. postalCode: type: string country: type: string description: The two-letter country code. examples: - address1: 6 Flagstone Drive address2: Apartment 2 city: Hudson state: NH postalCode: '03051' country: US CaseOrderDataEducation: title: CaseOrderDataEducation type: object description: >- The candidate data when `caseOrderDataTypeId` is `codt-education`. **Note:** Multiple properties are currently optional, but are strongly recommended to be included in requests. required: - institution - city - state - country - current - monthEnd - yearEnd properties: institution: type: string description: >- The name of the institution where the candidate received their education. educationType: example: College/University description: >- The type of education, such as a college or university, a high school or equivalent (for example, GED), a technical or trade school, or other. type: string educationTypeDescription: type: string description: >- A description of the education type. This should be used when `educationType` is other. degree: type: string description: >- The educational degree. Recommended when `educationType` is college/university or technical/trade school. major: type: string description: >- The candidate's field of study. Recommended when `educationType` is college/university or technical/trade school. city: type: string description: >- The city in which the institution is located. Recommended to be included in *all* requests. state: type: string description: >- The two-letter state code. Recommended to be included in *all* requests. country: type: string description: >- The two-letter country code. Recommended to be included in *all* requests. monthBegin: type: string description: The month in which the candidate began their education. yearBegin: type: string description: The year in which the candidate began their education. current: type: boolean description: >- If true, the candidate is currently enrolled at the institution. If false, the candidate is not currently enrolled. Recommended to be included in *all* requests. (Required true if `monthEnd` and `yearEnd` are not provided) default: false monthEnd: type: string description: >- The month in which the candidate completed their education. (Required if `current` is false or not provided) yearEnd: type: string description: >- The year in which the candidate completed their education. (Required if `current` is false or not provided) nameIfDifferentFlag: type: boolean description: >- If true, the candidate attended or is attending the institution under a different name. If false, the candidate's name on record with the institution is the same as the candidate's name recorded for the case. nameIfDifferent: type: string description: The candidate's name that's on record with the institution. contact: type: object description: >- The institution's contact information. **Known issue:** The API currently requires this object to be passed (either empty or with any of its optional properties). properties: website: type: string email: type: string phone: type: string secureDocumentIds: type: array description: >- The IDs of uploaded secure documents that will be associated to the education record. This optional field can be applied when providing data on behalf of the candidate. items: type: string CaseOrderDataEmployment: title: CaseOrderDataEmployment type: object description: >- The candidate data when `caseOrderDataTypeId` is `codt-employment`. **Note:** Multiple properties are currently optional, but are strongly recommended to be included in requests. required: - employer - position - city - state - country - monthBegin - yearBegin - current - monthEnd - yearEnd properties: employer: type: string description: >- The name of the candidate's current or former employer. Must be less than or equal to 100 characters. position: type: string description: The candidate's position with the employer. city: type: string description: >- The city of employment. Recommended to be included in *all* requests. state: type: string description: >- The two-letter state code. Recommended to be included in *all* requests. country: type: string description: >- The two-letter country code. Recommended to be included in *all* requests. monthBegin: type: string description: >- The month in which the candidate began their employment. Recommended to be included in *all* requests. yearBegin: type: string description: >- The year in which the candidate began their employment. Recommended to be included in *all* requests. current: type: boolean description: >- If true, the candidate is currently employed with the employer. If false, the candidate is no longer employed with the employer. Recommended to be included in *all* requests. (Required true if `monthEnd` and `yearEnd` are not provided) default: false monthEnd: type: string description: >- The month in which the candidate ended their employment. (Required if `current` is false or not provided) yearEnd: type: string description: >- The year in which the candidate ended their employment. (Required if `current` is false or not provided) contact: type: object description: >- The employer's contact information. **Known issue:** The API currently requires this object to be passed (either empty or with any of its optional properties). properties: website: type: string email: type: string phone: type: string okToContact: type: boolean description: >- If true, the employer can be contacted about the candidate. If false, the employer cannot be contacted. Recommended to be included in *all* requests. default: true incomeAmount: type: string description: >- The amount earned. This is applicable to Employment Income Verification. incomeFrequency: type: string description: >- The frequency of the amount earned. This is applicable to Employment Income Verification. example: Annually staffingAgency: type: string description: >- The Staffing Agency that the candidate is working for the employer through. (If applicable) maxLength: 100 secureDocumentIds: type: array description: >- The IDs of uploaded secure documents that will be associated to the employment record. This optional field can be applied when providing data on behalf of the candidate. items: type: string CaseOrderDataMVR: title: CaseOrderDataMVR type: object description: The candidate data when `caseOrderDataTypeId` is `codt-mvr`. required: - state - licenseNumber properties: state: type: string description: The two-letter state code of the candidate's driver's license. licenseNumber: type: string description: The candidate's driver's license number. firstNameIfDifferent: type: string description: >- If the name on the driver's license is different than the candidate name entered for the case, the first name on the candidate's driver's license. middleInitialIfDifferent: type: string description: >- If the name on the driver's license is different than the candidate name entered for the case, the middle initial on the candidate's driver's license. lastNameIfDifferent: type: string description: >- If the name on the driver's license is different than the candidate name entered for the case, the last name on the candidate's driver's license. CaseOrderDataAlias: title: CaseOrderDataAlias type: object description: The candidate data when `caseOrderDataTypeId` is `codt-alias`. required: - givenName - familyName properties: givenName: type: string description: >- Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. middleName: type: string description: >- Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. familyName: type: string description: >- Only letters, numbers, hyphens (-), apostrophes ('), commas (,), periods (.), and underscores (_) are allowed. CaseOrderDataJurisdiction: title: CaseOrderDataJurisdiction type: object description: The candidate data when `caseOrderDataTypeId` is `codt-address`. required: - city - state - county properties: city: type: string example: Manchester state: type: string description: The two-letter state code. example: NH county: type: string example: Hillsborough autoProcessJurisdictions: type: boolean default: false description: >- If true, jurisdiction order data will be automatically created based on the services ordered. If false, jurisdiction order data will be specified for the jurisdiction-based search type being ordered. CaseOrderDataJurisdictionCounty: title: CaseOrderDataJurisdictionCounty type: object description: >- The candidate data when `caseOrderDataTypeId` is `codt-jurisdiction-county`. required: - state - county properties: state: type: string description: The two-letter state code. example: NH county: type: string example: HILLSBOROUGH CaseOrderDataJurisdictionFederal: title: CaseOrderDataJurisdictionFederal type: object description: The candidate data when `caseOrderDataTypeId` is `codt-fed-district`. required: - district properties: district: type: string example: New Hampshire District Court CaseOrderDataJurisdictionState: title: CaseOrderDataJurisdictionState type: object description: >- The candidate data when `caseOrderDataTypeId` is `codt-jurisdiction-state`. required: - state properties: state: type: string description: The two-letter state code. example: NH CaseOrderDataCPLC: title: CaseOrderDataCPLC type: object description: The candidate data when `caseOrderDataTypeId` is `codt-cplc`. examples: - cplcId: cb3dac22-db86-44df-8193-877559b3e8dc fields: - fieldId: licenseNumber value: LN123456 - fieldId: firstName value: Lucian - fieldId: lastName value: Williams - fieldId: state value: NY required: - cplcId - fields properties: cplcId: type: string description: >- The unique ID of the professional license or certification. See [Professional license and certification](docs/reference/cplc.md) for a list of possible values. fields: type: array description: >- Details about the candidate's professional license or certification. Call [GET `/service/cplc/id/{cplcId}`](karma-api-openapi.yaml/paths/~1service~1cplc~1id~1{cplcId}/get) for a list of required fields for the specific professional license or certification. items: type: object required: - fieldId - value properties: fieldId: type: string enum: - licenseNumber - firstName - lastName - middleInitial - certifyingBody - state - additionalInfo - certifyingBodyMemberId - certifyingBodyVerificationPin - expirationDate - issueDate - licenseTitle description: >- The identifier for a specific detail of the professional license or certification. value: type: string description: The candidate's information corresponding to a specific field. secureDocumentIds: type: array description: >- The IDs of uploaded secure documents that will be associated to the CPLC record. This optional field can be applied when providing data on behalf of the candidate. items: type: string CaseOrderDataShipment: title: CaseOrderDataShipment type: object description: The candidate data when `caseOrderDataTypeId` is `codt-shipment`. examples: - recipientName: John Smith address1: 1952 Whitney Avenue address2: Unit 2 addressType: home addressSource: homeAddress city: Hamden state: CT postalCode: '06517' shippingMethod: Overnight maskType: Honeywell DC365 N95 - recipientName: John Smith c/o KC Clinic address1: 1952 Whitney Avenue addressType: clinic city: Hamden state: CT postalCode: '06517' shippingMethod: Overnight maskType: Honeywell DC365 N95 required: - recipientName - address1 - addressType - city - state - postalCode - shippingMethod - maskType properties: recipientName: type: string description: The recipient name. address1: type: string description: The recipient's street address. address2: type: string description: The recipient's street address, continued. addressType: enum: - home - clinic description: The address type. addressSource: enum: - homeAddress - newAddress description: >- The source of the address, which indicates whether the address is the same as the candidate's home address. This is used only when `addressType` is `home`. city: type: string description: The recipient's city. state: type: string description: The two-letter state code. postalCode: type: string description: The recipient's zip code. shippingMethod: description: The shipping method. enum: - 2-3 Business Days - Overnight maskType: type: string description: >- The mask SKU from [GET `/shipment/mask/list`](karma-api-openapi.yaml/paths/~1shipment~1mask~1list/get). CaseOrderDataOHSServiceSubstitutions: title: CaseOrderDataOHSServiceSubstitutions type: object description: >- The order data when `caseOrderDataTypeId` is `codt-ohs-service-substitutions`. The `substitutionMap` is an object where each key is a service ID, and the corresponding value is an array of service IDs that are acceptable alternatives for substitution. This mechanism is primarily intended for TB blood tests and drug panel services that are either identical or functionally equivalent. The goal is to expand clinic availability by allowing flexibility in the services that can be used to fulfill an order. examples: - substitutionMap: service-ohs-tb-quantiferon-gold: - service-ohs-tb-quantiferon-gold - service-ohs-tb-tspot-test service-drug-5-panel: - service-drug-5-panel - service-drug-300C-crl - service-drug-35105N-panel properties: substitutionMap: type: object description: >- The substitutionMap defines service ids that we can consider substituting. This is an object where each key is a service ID, and the corresponding value is an array of service IDs that are acceptable alternatives for substitution. additionalProperties: type: array items: type: string CaseOrderDataDocumentProcessing: title: CaseOrderDataDocumentProcessing type: object required: - documentTypeId - fileName - secureDocumentId properties: documentTypeId: type: string enum: - unclassified description: >- The identifier of the document type for the document to be processed. For the document processing flow this should always be `unclassified`. fileName: type: string description: The name of the file. example: sample-file-1.pdf secureDocumentId: type: string description: >- The identifier for the secureDocumentRecord the document is associated with. example: b7e2c1a2-1234-4f8b-9e2a-abcdef123456 Contact: title: Contact type: object description: Details of a contact. examples: - name: Dana R. type: default email: defaultcontact@example.com phone: 800-555-0150 - name: Alex P. type: escalation email: escalationcontact@example.com required: - type - email properties: name: type: string maxLength: 255 description: The name of the contact. type: type: string enum: - default - escalation description: The role of the contact. email: type: string description: The email address of the contact. format: email phone: type: string maxLength: 20 description: The phone number of the contact. ConfigValuesAlias: title: ConfigValuesAlias type: string enum: - no-alias - alias-all - alias-all+hits-only - alias-mnv - alias-mnv+hits-only description: The options for an alias configuration. default: no-alias ConfigValuesOhsDrugPassportExpirationPolicy: title: ConfigValuesOhsDrugPassportExpirationPolicy type: string enum: - company-default - reissue - reissue-and-contact - reissue-once-contact - contact-customer - do-not-reissue description: The configuration options for an ePassport expiration policy. default: company-default ConfigValuesDrugPolicy: title: ConfigValuesDrugPolicy type: string enum: - company-default - reorder - reorder-and-contact - reorder-once-contact - do-not-reorder description: The configuration options for a drug policy. default: company-default ConfigValuesEmploymentVerification: title: ConfigValuesEmploymentVerification type: string enum: - docs-acceptable - psv - psv-first description: The configuration options for employment verification. default: docs-acceptable ConfigValuesEducationVerification: title: ConfigValuesEducationVerification type: string enum: - docs-acceptable - psv - psv-first description: The configuration options for education verification. default: docs-acceptable ConfigValuesQuantiferon: title: ConfigValuesQuantiferon type: string enum: - company-default - replace-with-t-spot - do-not-replace description: The options for Quantiferon substitution. default: company-default ConfigValuesTspot: title: ConfigValuesTspot type: string enum: - company-default - replace-with-quantiferon - do-not-replace description: The options for T-Spot substitution. default: company-default securitySchemes: JWT: type: http scheme: bearer ````