swagger: '2.0' info: title: Business Verifications description: >- This API manages the set of operations that allow financial institutions to verify business identities as well as the identities of authorized representatives connected to the business. Vetting business identites can help financial institutions standardize and build consistency in decisioning processes. This vetting consists of verifying the business as well as the authorized signers associated with the business. **Buisness Identification consists of the following attributes:** * `businessName` The name of the business * `addressLine1` Line 1 of the businesses street address * `addressLine2` Line 2 of the businesses street address * `city` The businesses city * `regionCode` The businesses region code * `postalCode` The businesses postal code * `countryCode` The businesses country code * `identification.taxId` The business's tax ID number (Federal Employer Identification Number) **Authorized Signer Identification consists of the following attributes:** * `firstName` The legal first name of the authorized signer * `lastName` The legal last name of the authorized signer * `identification.taxId` The federal tax ID of the authorized signer _A verification report accepts an array of authorized signers to allow for verifying multiple identities associated with a business._ ## Submitting a request to generate a verification report A _verification report_ can be generated by passing the above data points in a `POST /verificationReports`. The response will contain an *`input`* object which will echo the data that was sent on the POST request. It will also contain an *`output`* object which will hold the unique `transactionId` and state for the report as well as any risk factors, risk factor codes and risk factor descriptions flagged by the report. It is possible to link an organization resource to a verification report by passing an `apiture:organization` URI in the `_links` object when calling a `POST /verificationReports`. If the optional `apiture:organization` link is supplied to the `POST /businessVerifications` call, you can retrieve that organizations verification status by calling `GET /businessVerifications?organizationUri={organizationUri}`. If `apiture:organization` is not included in this `POST`, results can be retrieved by calling `GET /verificationReports/{verificationReportId}` ## Checking the verification status for an organization If the optional `apiture:organization` link was passed on the `POST /verificationReports`, it is possible to view the verification status of that organization by calling `GET /businessVerifications?organizationUri=/organization/organization/{organizationId}`. The response from `GET /businessVerifications` will contain an embedded list of of *`businessVerifications`*, each of which will contain a *`type`*. The two possible values are *`verificationReport`* or *`administratorApproval`*. A *`verificationReport`* will point back to a verification report resource. An *`administratorApproval`* will point back to an Approval resource. The presence of an *`administratorApproval`* record signifies that a member of the financial institution has made a decision regarding the verification status of an organization. This decision acts as an override to any previous verification report results. If a verification report is run and successfully verifies the identity of the business, an approval record will be automatically generated with a `state: 'passed'`. version: 0.1.0 contact: name: Apiture url: 'https://developer.aptiture.com' email: api@apiture.com termsOfService: Pending schemes: - https basePath: /businessVerifications consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: API description: Endpoints which describe this API. - name: Verification Report description: Business VerificationReport - name: Verification Status description: Check verification status of a business - name: Configuration description: >- A set of endpoints that allows for the creation and retrieval of configuration options specific to this service paths: /verificationReports: get: summary: Return a collection of verification reports description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of verification reports which have been run in the past. The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getVerificationReports security: - apiKey: [] accessToken: - profiles/read x-apiture-implemented: true tags: - Verification Report parameters: - name: start in: query description: >- The zero-based index of the first verification report item to include in this page. The default 0 denotes the beginning of the collection. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of verification report representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/verificationReports' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' post: summary: Create a new verification report description: >- Create a new verification report in the verification reports collection. If the optional `apiture:organization` link is supplied in this request, the verification report will be linked to the Organization. In addition you will be able to retrieve that organizations verification status by calling `GET /businessVerifications?organizationUri={organizationUri}`. If the `apiture:organization` link is _not_ included in this `POST` reuest, the verification report and results can only be retrieved by calling `GET /verificationReports/{verificationReportId}`. If the supplied `apiture:organization` URI is invalid, a 400 Bad Request will be returned. The following `_links` will be included in a succesful response * `self` - URI of the created verification report resource - `/verificationReports/{verificationReportId}` * `apiture:organization` - If the resource was created with an `apiture:organization` a link to the specified resource will be present operationId: createVerificationReport security: - apiKey: [] accessToken: - profiles/write x-apiture-implemented: true tags: - Verification Report parameters: - name: verificationRequest in: body description: The data necessary to create a new verification report. required: true schema: $ref: '#/definitions/createVerificationReport' responses: '201': description: Created schema: $ref: '#/definitions/verificationReport' headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. type: string '400': $ref: '#/responses/400VerificationReport' '/verificationReports/{verificationReportId}': get: summary: Fetch a representation of this verification report description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this verification report resource. The following links will be included in a successful response under the `_links` property: * `self` - URI of the this verification report resource - `/verificationReports/{verificationReportId}` * `apiture:organization` - If the resource was created with an `apiture:organization`, a link to the specified resource will be present operationId: getVerificationReport security: - apiKey: [] accessToken: - profiles/read x-apiture-implemented: true tags: - Verification Report parameters: - $ref: '#/parameters/verificationReportIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/verificationReport' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this verification report resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404VerificationReport' /businessVerifications: get: summary: Retrieves business verification resources. description: >- Retrieves the business verification status. This operation requires an `organizationUri` matching the`apiture:organization` link that was supplied on the `POST /verificationReports`. If the `organizationUri` link is invalid a 400 Bad Request response will be returned. The following links will be included in a successful response under the _links property: * `apiture:organization`: If the specified `organizationUri` param refers to an organization resource a link to it will be present The response will contain an embedded list of of businessVerifications, each of which will contain a `type`. The two possible values are: * `verificationReport` * `administratorApproval` A `verificationReport` will point back to a `verificationReport` resource. An `administratorApproval` will point back to an `apiture:approval` resource. The presence of an `administratorApproval` record signifies that a member of the financial institution has made a decision regarding the verification status of an Organization. This decision acts as an override to any previous verification report results. operationId: getBusinessVerifications security: - apiKey: [] accessToken: - profiles/read tags: - Verification Status parameters: - $ref: '#/parameters/organizationUriParam' - name: type description: The identity method type. Possible values are `verificationReport` or `administratorApproval`. type: string in: query required: false enum: - verificationReport - administratorApproval responses: '200': description: OK schema: $ref: '#/definitions/businessVerifications' '400': $ref: '#/responses/400BusinessVerifications' /configuration: get: summary: Configuration definition for this API description: Returns the configuration for this API operationId: getConfiguration security: - apiKey: [] accessToken: - admin/read x-apiture-implemented: true tags: - Configuration responses: '200': description: OK schema: $ref: '#/definitions/configuration' /configuration/groups: get: summary: Return a collection of configuration groups description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of configuration groups. The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getConfigGroups security: - apiKey: [] accessToken: - admin/read tags: - Configuration parameters: - name: start in: query description: >- The zero-based index of the first configuration group item to include in this page. The default 0 denotes the beginning of the collection. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of configuration group representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/configurationGroups' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' '/configuration/groups/{groupName}': get: summary: Fetch a representation of this configuration group description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this configuration group resource. operationId: getConfigGroup security: - apiKey: [] accessToken: - admin/read tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/configurationGroup' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-None-Match` request header for *`GET`* operations for this configuration group resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404ConfigurationGroup' '/configuration/groups/{groupName}/schema': get: summary: Fetch the schema for this configuration group description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this configuration group schema resource. operationId: getConfigGroupSchema security: - apiKey: [] accessToken: - admin/read tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/configurationSchema' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404ConfigurationGroup' '/configuration/groups/{groupName}/values': get: summary: Fetch the values for the specified configuration group description: >- Return a representation of this configuration group values resource. operationId: getConfigGroupValues security: - apiKey: [] accessToken: - admin/read tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/configurationValues' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404ConfigurationGroup' put: summary: Update the values for the specified configuration group description: Perform a complete replacement of this set of values operationId: updateConfigGroupValues security: - apiKey: [] accessToken: - admin/write tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - name: configuration group values in: body required: true schema: $ref: '#/definitions/configurationValues' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/configurationSchema' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* type: string '400': $ref: '#/responses/400' '404': $ref: '#/responses/404ConfigurationGroup' '412': $ref: '#/responses/412' '428': $ref: '#/responses/428' '/configuration/groups/{groupName}/values/{valueName}': get: summary: Fetch a single value associated with the specified configuration group description: >- Fetch a single value associated with this configuration group. This provides convenient access to the map of `values` of the configuration group. To update a specific value, use `PUT /businessVerifications/configuration/groups/{groupName}/values/{valueName}` (operation `updateConfigurationGroupValue`). operationId: getConfigGroupValue security: - apiKey: [] accessToken: - admin/read tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - $ref: '#/parameters/configurationGroupValueNamePathParam' responses: '200': description: OK schema: type: object headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this configuration group resource. type: string '404': $ref: '#/responses/404ConfigurationGroupOrValue' put: summary: Update a single value associated with the specified configuration group description: >- Update a single value associated with this configuration group. This provides convenient access to individual `values` of the configuration group as defined in the configuration group's `schema`. The request body must conform to the configuration group's schema for the named `{valueName}`. This operation is idempotent. To update a specific value, use `PUT /businessVErifications/configuration/groups/{groupName}/values/{valueName}` (operation `updateConfigurationGroupValue`). operationId: updateConfigGroupValue security: - apiKey: [] accessToken: - admin/write tags: - Configuration parameters: - $ref: '#/parameters/configurationGroupNamePathParam' - $ref: '#/parameters/configurationGroupValueNamePathParam' - name: values in: body required: true schema: $ref: '#/definitions/attributes' responses: '200': description: OK schema: type: object headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this configuration group resource. type: string /: get: summary: Top-level resources and operations in this API description: Return links to the top-level resources and operations in this API. operationId: getApi security: - apiKey: [] x-apiture-implemented: true responses: '200': description: OK schema: $ref: '#/definitions/root' tags: - API /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc security: - apiKey: [] x-apiture-implemented: true produces: - application/json - application/openapi+json;version=2.0 - application/openapi+yaml;version=2.0 responses: '200': description: OK schema: type: object tags: - API parameters: configurationGroupNamePathParam: name: groupName description: The unique name of this configuration group. in: path type: string required: true configurationGroupValueNamePathParam: name: valueName description: >- The unique name of a value in a configuration group. This is the name of the value in the `schema`. A `{valueName}` must be a simple identifier following the pattern _`letter [letter | digit | '-' | '_']*`_ in: path type: string required: true verificationReportIdPathParam: name: verificationReportId description: >- The unique identifier of this verification report. This is an opaque string. in: path type: string required: true filterQueryParam: name: filter in: query description: >- Optional filter criteria. See [filtering](http://docs.apiture.com/api/concepts/filtering#criteria). type: string qQueryParam: name: q in: query description: >- Optional search string. See [searching](http://docs.apiture.com/api/concepts/searching). type: string ifMatchHeaderParam: name: If-Match description: >- The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource. in: header type: string required: true ifNoneMatchHeaderParam: name: If-None-Match description: >- The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified) and no response body, else the resource representation will be returned. in: header type: string organizationUriParam: name: organizationUri description: The `apiture:organization` URI. in: query type: string required: true securityDefinitions: apiKey: type: apiKey name: API-Key in: header description: >- API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the `API-Key: {api-key}` request header. accessToken: type: oauth2 flow: accessCode description: >- OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. authorizationUrl: 'https://auth.apiture.com/oauth2/authorize' tokenUrl: 'http://auth.apiture.com/auth/oauth2/token' scopes: profiles/read: Read access to user and contact related resources. profiles/write: Write (update) access to user and contact related resources. profiles/delete: Delete access to user and contact related resources. profiles/readPii: >- Read access to perssonally identifiable information such as tax ID numbers, phone numbers, email and postal addresses. This must be granted in addition to the `profiles/read` scope in order to read such data, but is included in the `profiles/full` scope. profiles/full: Full access to user and contact related resources. admin/read: Read access to system configuration. admin/write: Write (update) access to system configuration. admin/full: Full access to system configuration. responses: '304': description: >- Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' '412': description: >- Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim. schema: $ref: '#/definitions/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' '428': description: >- Precondition Required. The request did not include the required `if-Match` header. Resubmit with the operation, supplying the value of the `ETag` and the most recent state of the resource. schema: $ref: '#/definitions/errorResponse' 400BusinessVerifications: description: >- Bad Request. The Organization URI was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedOrganizationUri 400VerificationReport: description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedRequestBody 404VerificationReport: description: >- Not Found. There is no such verification report resource at the specified `{verificationReportId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidReportId 204Deleted: description: No Content. The resource was deleted successfully. 404ConfigurationGroup: description: >- Not Found. There is no such configuration group resource at the specified `{groupName}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/error' 404ConfigurationGroupOrValue: description: >- Not Found. There is either no such configuration group resource at the specified `{groupName}` or no such value at the specified `{valueName}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/error' definitions: verificationRequestFields: title: Verification Request Fields description: >- Common fields of a verification request, used to build other model schemas. properties: businessName: description: "The business's name" type: string maxLength: 512 minLength: 1 alternateBusinessName: description: An alternate name for the business type: string maxLength: 512 minLength: 1 phone: description: "The business's phone" type: string maxLength: 32 minLength: 1 identification: $ref: '#/definitions/identificationModel' authorizedSigners: description: An optional array of authorized signer entities type: array items: $ref: '#/definitions/authorizedSigner' addresses: description: An array of postal mailing addresses for this contact. type: array items: type: object $ref: '#/definitions/address' attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the verification report. example: businessName: ABC EXAMPLE CO. phone: 555-555-1234 identification: - type: 'taxId' value: '12-347894309' attributes: {} addresses: - addressLine1: 3212 N. 2nd Ave. city: Wilmington regionCode: NC postalCode: '28412' authorizedSigners: - firstName: Jane lastName: Doe identification: - type: 'taxId' value: '121-34-5431' birthdate: '1980-12-01' email: email@email.com address: title: Address description: A postal address. type: object required: - addressLine1 - city - regionCode - postalCode properties: label: description: >- A text label, suitable for presentation to the user. This is also used if `type` is `other`. type: string addressLine1: description: >- The first street address line of the address, normally a house number and street name. type: string addressLine2: description: >- The optional second street address line of the address. type: string city: description: >- The name of the city or municipality. type: string regionCode: description: >- The mailing address region code, such as state in the US, or a province in Canada. type: string example: NC postalCode: description: >- The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code. type: string example: 28401-5405 countryCode: description: The ISO 3166-1 country code. type: string minLength: 2 maxLength: 2 createVerificationReport: title: Create Verification Report description: >- Representation used to create a new verification report. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/verificationRequestFields' example: _profile: 'http://api.apiture.com/schemas/businessVerifications/verificationReports/v1.0.0/profile.json' verificationReportScoringSummary: title: Verification Report Summary description: >- Model schema for business verification report summary properties: transactionId: description: The unique transactionId for this verification report used for tracking this verification report type: string state: type: string description: The state of a verification report. _passed_ indicates that the Business was successfully verified based upon the supplied information, _failed_ indicates it was not. enum: - passed - failed businessVerifications: type: array items: $ref: '#/definitions/businessVerificationScore' businessRiskFactors: type: array items: $ref: '#/definitions/riskFactor' comprehensiveVerificationScores: type: array items: $ref: '#/definitions/comprehensiveVerificationScore' authorizedRepresentativeRiskFactors: type: array items: $ref: '#/definitions/riskFactor' riskFactor: title: Risk Factor description: Risk factors, warning codes, or risk codes are not necessarily indicators of fraud or of any fraudulent intent. They are value added attributes that indicate information that may have contributed to a lower score. properties: riskCode: description: The risk factor risk code type: string description: description: The risk code description type: string comprehensiveVerificationScore: title: Authorized Representative Comprehensive Verification Score description: The comprehensive verification score is a risk verification score for the authorized representative properties: inputRepNumber: description: the rep number for the authorized representative type: string score: description: The comprehensive verification score is a risk verification score of the authorized representative type: integer description: description: The description for the CVI value type: string businessVerificationScore: title: Business Verification Score description: An score that summarizes the verification of the input information. This objects contains a score `value` and accompanying `description`. properties: value: description: The business verification score value type: string description: description: The business verification score description type: string summaryVerificationReport: title: Verification Report Summary description: >- Summary representation of a verification report resource in verification report collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _id: description: >- The unique identifier for this verification report resource. This is an immutable opaque string. type: string reportScoringSummary: $ref: '#/definitions/verificationReportScoringSummary' example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/businessVerifications/verificationReports/v1.0.0/profile.json' _links: self: href: /businessVerifications/verificationReports/0399abed-fd3d-4830-a88b-30f38b8a365c verificationReport: title: Verification Report description: >- Representation of verification report resources. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/summaryVerificationReport' - type: object properties: createdAt: description: An ISO 8601 UTC time stamp indicating when the verification report was created. type: string format: date-time _embedded: description: The objects which participate in this verification report type: object input: $ref: '#/definitions/createVerificationReport' reportScoringSummary: $ref: '#/definitions/verificationReportScoringSummary' reportResults: description: >- The raw verification report results type: object example: createdAt: '2018-04-17T10:04:46.375Z' _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _embedded: {} input: businessName: ABC EXAMPLE CO. phone: 555-555-1234 identification: - type: 'taxId' value: '12-347894309' authorizedSigners: - firstName: Jane lastName: Doe identification: - type: 'taxId' value: '121-34-5431' birthdate: '1980-12-01' email: email@email.com addresses: - addressLine1: 3212 N. 2nd Ave. city: Wilmington regionCode: NC postalCode: '28412' reportScoringSummary: transactionId: 578490325jk439834yuf43 state: failed businessVerification: - value: 40 description: Strong verification of the input data is confirmed businessRiskFactors: - riskCode: '20' description: 'Unable to verify business address on business records' - riskCode: '21' description: 'Unable to verify business TIN on business records' comprehensiveVerificationScores: - inputRepNumber: '1' score: 20 description: 'Full name, address, phone, SSN verified' authorizedRepresentativeRiskFactors: - riskCode: '81' description: 'The input date-of-birth was missing or incomplete' - riskCode: '25' description: 'Unable to verify address' reportResults: {} verificationReports: title: Verification Report Collection description: >- Collection of verification reports. The items in the collection are ordered in the `_embedded.items` array; the `name` is `verificationReports`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) allOf: - $ref: '#/definitions/collection' - type: object properties: _embedded: type: object properties: items: description: An array containing a page of verification report items. type: array items: $ref: '#/definitions/summaryVerificationReport' example: _profile: 'http://api.apiture.com/schemas/businessVerifications/verificationReports/v0.1.0/profile.json' start: 10 limit: 10 count: 67 name: verificationReports _links: self: href: /businessVerifications/verificationReports?start=10&limit=10 first: href: /businessVerifications/verificationReports?start=0&limit=10 next: href: /businessVerifications/verificationReports?start=20&limit=10 collection: href: /businessVerifications/verificationReports _embedded: items: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: >- http://api.apiture.com/schemas/businessVerifications/verificationReports/v0.1.0/profile.json _links: self: href: /businessVerifications/verificationReports/0399abed-fd3d-4830-a88b-30f38b8a365c apiture:organization: href: /organizations/organizations/6734fdsa-fd3d-4830-a88b-30f38b8a365c reportScoringSummary: transactionId: 578490325jk439834yuf43 state: failed businessVerification: - value: 40 description: Strong verification of the input data is confirmed businessRiskFactors: - riskCode: '20' description: 'Unable to verify business address on business records' - riskCode: '21' description: 'Unable to verify business TIN on business records' comprehensiveVerificationScores: - inputRepNumber: '1' score: 20 description: 'Full name, address, phone, SSN verified' authorizedRepresentativeRiskFactors: - riskCode: '81' description: 'The input date-of-birth was missing or incomplete' - riskCode: '25' description: 'Unable to verify address' collection: title: Collection description: >- A collection of resources. This is an abstract model schema which is extended to define specific resource collections. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: count: description: The number of items in the full collection.. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string authorizedSigner: title: Authorized Signer description: >- Authorized Signers are primary bank users and co-owners of a business, optionally passed when creating verification reports. required: - firstName - lastName properties: firstName: description: The authorized signer's first name type: string maxLength: 512 minLength: 1 lastName: description: The authorized signer's last name type: string maxLength: 512 minLength: 1 identification: $ref: '#/definitions/identificationModel' birthdate: description: The authorized signer's birth date in `yyyy-mm-dd` format. type: string format: date pattern: '^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))$' maxLength: 10 minLength: 10 email: description: The authorized signer's email address type: string maxLength: 512 minLength: 1 example: firstName: Jane lastName: Doe identification: - type: 'taxId' value: '121-34-5431' birthdat>: '1980-12-01' email: email@email.com identificationModel: description: >- A collection of official identifying information associated with an entity. type: array items: type: object required: - type - value properties: value: description: >- The value of this form of identification (the tax ID as a string, for example) type: string type: description: >- The type of this form of identification. For a person, `taxId` is their federal tax ID (such as social security number). For a business, `taxId` is the [_Federal Employer Identification Number_](https://www.irs.gov/businesses/small-businesses-self-employed/employer-id-numbers) or FEIN (also known as _Tax Identification Number_ or TIN), and `dunsNumber` is the business' [_Dun & Bradstreet Number_](https://fedgov.dnb.com/webform). type: string enum: - taxId - dunsNumber businessVerification: title: Business Verification Report description: >- The verification report contains analsys of the business data and includes the state of the verification. properties: state: type: string description: The state of a verification report. _passed_ indicates that the Business was successfully verified based upon the supplied information, _failed_ indicates it was not. enum: - passed - failed completedAt: description: An ISO 8601 UTC time stamp indicating when the verification report was created. type: string format: date-time type: description: The identity method type. Possible values are `verificationReport` or `administratorApproval`. type: string enum: - verificationReport - administratorApproval _id: type: string description: This business verification's unique id _links: $ref: '#/definitions/links' businessVerifications: title: Business Verifications description: >- Representation of the verification results that were previously generated by this service via the `POST /businessVerifications`. The result contains a link to `apiture:organization` if an `apiture:organization` link was passed on the request to create the report. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: businessVerifications: description: An array of business verification resources type: array items: $ref: '#/definitions/businessVerification' example: businessVerifications: - state: failed completedAt: '2018-04-17T10:04:46.375Z' type: 'verificationReport' _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _links: apiture:verificationReport: href: /businessVerifications/verificationReports/0399abed-fd3d-4830-a88b-30f38b8a365c - state: passed completedAt: '2018-04-17T10:04:46.375Z' type: 'administratorApproval' _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _links: apiture:approval: href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c configuration: title: Configuration description: >- Represents the configuration for the Business Verifications API properties: _links: $ref: '#/definitions/links' example: _links: self: href: /businessVerifications/configuration/ 'apiture:groups': href: /businessVerifications/configuration/groups configurationGroups: title: Configuration Group Collection description: >- Collection of configuration groups. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _embedded: type: object properties: items: description: An array containing a page of configuration group items. type: array items: $ref: '#/definitions/configurationGroupSummary' example: _profile: 'http://api.apiture.com/schemas/businessVerifications/configurationGroups/v1.0.0/profile.json' start: 10 limit: 10 count: 67 name: configurationGroups _links: self: href: /businessVerifications/configuration/groups?start=10&limit=10 first: href: /businessVerifications/configuration/groups?start=0&limit=10 next: href: /businessVerifications/configuration/groups?start=20&limit=10 collection: href: /businessVerifications/configuration/groups _embedded: items: - _profile: 'http://api.apiture.com/schemas/businessVerifications/configurationGroup/v1.0.0/profile.json' _links: self: href: /configuration/groups/rules 'apiture:configuration': href: /configuration name: rules label: Verification Rules description: The basic pass-fail verification rules for the Business Verifications API configurationGroupSummary: title: Configuration Group Summary description: >- A summary of the data contained within a configuration group resource allOf: - $ref: '#/definitions/abstractResource' - type: object properties: name: description: >- The name of this configuration group, must be unique within the set of all resources of this type. type: string maxLength: 48 minLength: 1 pattern: '[a-zA-Z][-\w_]*' example: businessVerifications label: description: >- The text label for this resource, suitable for presentation to the client. type: string maxLength: 128 minLength: 1 example: 'Business Verifications Configuration' description: description: >- The full description for this resource, suitable for presentation to the client. type: string maxLength: 4096 minLength: 1 example: >- The configuration for the Business Verifications API. configurationGroup: title: Configuration Group description: >- Represents a configuration group. allOf: - $ref: '#/definitions/configurationGroupSummary' - type: object properties: schema: $ref: '#/definitions/configurationSchema' values: $ref: '#/definitions/configurationValues' example: _profile: 'http://api.apiture.com/schemas/businessVerifications/configurationGroup/v1.0.0/profile.json' _links: self: href: /configuration/groups/rules 'apiture:configuration': href: /configuration name: rules label: Verification Rules description: The basic pass-fail verification rules for the Business Verifications API schema: type: object properties: minBusinessVerificationScore: type: string description: The minimum pass score for Business Verification minAuthRepVerificationScore: type: string description: The minimum pass score for Authorized Rep Verification minCombinedVerificationScore: type: string description: The minimum combined Business and Rep Verification Score autoFailBizRiskFactors: type: string description: Array of auto fail business risk factors autoFailEntityRiskFactors: type: string description: Array of auto fail entity risk factors values: minBusinessVerificationScore: '30' minAuthRepVerificationScore: '30' minCombinedVerificationScore: '70' autoFailBizRiskFactors: '' autoFailEntityRiskFactors: '' configurationSchema: title: Configuration Schema description: >- The schema which defines the name and types of the variables that are part of this configuration definition. Property names must be simple identifiers consisting of alphanumeric characters, `-`, `_` following the pattern _`letter [letter | digit | '-' | '_']*`_ This is implicitly a schema for `type: object` and contains the properties. The `values` in a configuration conform to the schema. The names and types are described with a subset of [JSON Schema Core](https://tools.ietf.org/html/draft-zyp-json-schema-04) and [JSON Schema Validation](https://tools.ietf.org/html/draft-fge-json-schema-validation-00) similar to that used to define schemas in [OpenAPI Specification 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject). example: type: object properties: minBusinessVerificationScore: type: string description: The minimum pass score for Business Verification minAuthRepVerificationScore: type: string description: The minimum pass score for Authorized Rep Verification minCombinedVerificationScore: type: string description: The minimum combined Business and Rep Verification Score autoFailBizRiskFactors: type: string description: Array of auto fail business risk factors autoFailEntityRiskFactors: type: string description: Array of auto fail entity risk factors configurationValues: title: Configuration Values description: >- The data associated with this configuration: the resource's variable names and values. These values must conform to this item's `schema`. *Note*: the `schema` may also contain `default` values which, if present, are used if a value is *not* set in the definition's `values`. (For example, multiple configurations may use the same schema that defines values `a`, `b`, and `c`, but each configuration may have their own unique values for `a`, `b`, and `c` which is separate from the schema.) example: minBusinessVerificationScore: '30' minAuthRepVerificationScore: '30' minCombinedVerificationScore: '70' autoFailBizRiskFactors: '' autoFailEntityRiskFactors: '' abstractResource: title: Abstract Resource description: >- An augmented [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. example: _profile: 'http://api.apiture.com/schemas/example/v1.0.0/profile.json' _links: self: href: '{uri of current resource}' apiture:organization: href: /organizations/organizations/6734fdsa-fd3d-4830-a88b-30f38b8a365c properties: _links: $ref: '#/definitions/links' _embedded: description: >- An optional map of nested resources, mapping each nested resource name to a nested resource representation. type: object _profile: description: >- The URI of a [resource profile](http://doc.apiture.com/api/concepts/resource-profile) which describes the representation. type: string format: uri _error: description: >- An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' root: title: API Root description: >- A HAL response, with hypermedia `_links` for the top-level resources and operations in API. example: id: apiName name: API name apiVersion: 0.0.1-SNAPSHOT _profile: 'https://api.apiture.com/schemas/root/v1.0.0/profile.json' _links: {} allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _id: type: string description: This API's unique ID. name: type: string description: This API's name. apiVersion: type: string description: This API's version. errorResponse: title: Error Response description: >- Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details. allOf: - $ref: '#/definitions/abstractResource' example: _profile: 'http://api.apiture.com/schemas/error/v1.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: 2018-01-25T05:50:52.375Z _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] error: title: Error description: >- An error description. Nested source errors are contained in the `_embedded` object with the key `"errors"`; this is an array of nested error objects. For example, an API which validates its request body may find multiple errors in the request, which may be detailed here. The `_links` may contain a `describedby` link which refers to a web page with details about the error. The `attributes` field An optional map of name/value pairs which provide structured data about the error. For example, if the error is a value out of range, the attributes may specify the range values `min` and `max`. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). required: - message properties: message: type: string description: A localized message string describing the error condition. _id: type: string description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: An ISO 8601 UTC time stamp indicating when the error occurred. example: '2018-02-02T03:37:15.375Z' attributes: description: >- Data attribute associated with the error, such as values or constraints. allOf: - $ref: '#/definitions/attributes' remediation: type: string description: >- An optional localized string which provides hints for how the user or client can resolve the error. _embedded: description: >- Optional embedded array of errors. This field may not exist if the error does not have nested errors. type: object properties: items: description: An array of error objects. type: array items: $ref: '#/definitions/errorResponse' example: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] attributes: title: Attributes description: >- An optional map of name/value pairs which contains additional dynamic data about the resource. type: object links: title: Links description: >- An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. type: object additionalProperties: $ref: '#/definitions/link' link: title: Link description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: >- The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: >- If true, the link's href is a [URI template](https://tools.ietf.org/html/rfc6570). title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: >- If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. profile: type: string format: uri description: >- The URI of a profile document, a JSON document which describes the target resource/operation. x-apiture-errors: invalidReportId: description: No Reports were found for the specified reportId remediation: Check to make sure that the supplied reportId corresponds to an apiture report resource malformedOrganizationUri: description: The supplied organizationUri was malformed remediation: Check to make sure that the supplied organizationUri corresponds to an apiture organization resource attributes: properties: exampleOrganizationUri: '/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c' malformedRequestBody: description: The supplied request body was malformed remediation: Check to make sure that your request body exists and that it does not contain syntax errors x-apiture-traits: - api: title: Business Verifications basePath: businessVerifications links: [ getApi, getApiDoc, getVerificationReports, createVerificationReport, getBusinessVerifications, getConfiguration, getConfigGroups, ] - resource: name: verification report pluralName: verificationReports description: >- A report that verifies identity information for an Organization given a set of data points. simpleModelSchema: true paginated: true sortable: true searchable: true filterable: true patch: false delete: false - security: baseScope: profiles