{ "swagger": "2.0", "info": { "title": "Organizations", "description": "Contact information for organizations (businesses, non-profits, trusts, etc.) within the Apiture Banking APIs.", "version": "0.2.0", "contact": { "name": "Apiture", "url": "https://developer.apiture.com", "email": "api@apiture.com" }, "termsOfService": "TODO: Terms of Service is TBD; need input from Legal team." }, "schemes": [ "https" ], "basePath": "/organizations", "consumes": [ "application/hal+json", "application/json" ], "produces": [ "application/hal+json", "application/json" ], "tags": [ { "name": "API", "description": "Endpoints which describe this API." }, { "name": "Organization", "description": "Organization" } ], "paths": { "/organizations": { "get": { "summary": "Return a collection of organizations", "description": "Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching) collection of organizations. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.", "operationId": "getOrganizations", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "name": "start", "in": "query", "description": "The zero-based index of the first organization 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 organization 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](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`." }, { "$ref": "#/parameters/filterQueryParam" }, { "$ref": "#/parameters/qQueryParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organizations" } }, "400": { "$ref": "#/responses/400" }, "422": { "$ref": "#/responses/422" } } }, "post": { "summary": "Create a new organization", "description": "Create a new organization in the organizations collection.", "operationId": "createOrganization", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "name": "organization", "in": "body", "description": "The data necessary to create a new organization.", "required": true, "schema": { "$ref": "#/definitions/createOrganization" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/organization" }, "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/400" } } } }, "/organizations/{organizationId}": { "get": { "summary": "Fetch a representation of this organization", "description": "Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this organization resource.", "operationId": "getOrganization", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "$ref": "#/parameters/organizationIdPathParam" }, { "$ref": "#/parameters/ifNoneMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 organization resource.", "type": "string" } } }, "304": { "$ref": "#/responses/304" }, "404": { "$ref": "#/responses/404Organization" } } }, "put": { "summary": "Update this organization", "description": "Perform a complete replacement of this organization.", "operationId": "updateOrganization", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "$ref": "#/parameters/organizationIdPathParam" }, { "name": "organization", "in": "body", "required": true, "schema": { "$ref": "#/definitions/updateOrganization" } }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 organization resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400" }, "404": { "$ref": "#/responses/404Organization" }, "412": { "$ref": "#/responses/412" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } }, "patch": { "summary": "Update this organization", "description": "Perform a partial update of this organization. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included.", "operationId": "patchOrganization", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "$ref": "#/parameters/organizationIdPathParam" }, { "name": "organization", "in": "body", "required": true, "schema": { "$ref": "#/definitions/updateOrganization" } }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 organization resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400" }, "404": { "$ref": "#/responses/404Organization" }, "412": { "$ref": "#/responses/412" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } }, "delete": { "summary": "Delete this organization resource", "description": "Delete this organization resource.", "operationId": "deleteOrganization", "x-apiture-implemented": true, "tags": [ "Organization" ], "parameters": [ { "$ref": "#/parameters/organizationIdPathParam" } ], "responses": { "204": { "$ref": "#/responses/204" } } } }, "/": { "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", "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", "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" ] } }, "/activeOrganizations": { "post": { "summary": "Activate an organization.", "tags": [ "Organization" ], "description": "Activate an organization from an inactive state.
This operation is invoked from the `apiture:activate` link on an organization resource when that user is eligible to be activated.
This changes the `state` to `active`.", "operationId": "activateOrganization", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/organizationQueryParam" }, { "name": "organizationUri", "description": "The URI of an existing organization which is eligible to be activated. This parameter is **deprecated**. Use the `?organization=` query parameter instead.", "type": "string", "in": "query" }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 user resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Organization" }, "409": { "$ref": "#/responses/409OrganizationConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } }, "/inactiveOrganizations": { "post": { "summary": "Deactivate an organization.", "tags": [ "Organization" ], "description": "Deactivate an organization from an active state.
This operation is invoked from the `apiture:deactivate` link on an organization resource when that user is eligible to be deactivated.
This changes the `state` to `inactive`.", "operationId": "deactivateOrganization", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/organizationQueryParam" }, { "name": "organizationUri", "description": "The URI of an existing organization which is eligible to be deactivated. This parameter is **deprecated**. Use the `?organization=` query parameter instead.", "type": "string", "in": "query", "required": true }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 user resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Organization" }, "409": { "$ref": "#/responses/409OrganizationConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } }, "/removedOrganizations": { "post": { "summary": "Remove an organization.", "tags": [ "Organization" ], "description": "Remove an organization by setting its state to `removed`.
This operation is invoked from the `apiture:remove` link on a organization resource when that user is eligible to be removed. The organization must not be in use (there may not be any active associations to the organization.)
This changes the `state` to `removed`.", "operationId": "removeOrganization", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/organizationQueryParam" }, { "name": "organizationUri", "description": "The URI of an existing organization which is eligible to be removed. This parameter is **deprecated**. Use the `?organization=` query parameter instead.", "type": "string", "in": "query", "required": true }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/organization" }, "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 user resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Organization" }, "409": { "$ref": "#/responses/409OrganizationConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } } }, "parameters": { "organizationIdPathParam": { "name": "organizationId", "description": "The unique identifier of this organization. This is an opaque string.", "in": "path", "type": "string", "required": true }, "organizationQueryParam": { "name": "organization", "description": "A string which identifies existing organization whose state is being changed by `POST`ing it to a resource set. The server supplies this value when returning a link to operate on a specific organization. The value may be a `{organizationId}` or a organization URI.", "type": "string", "in": "query", "required": true }, "filterQueryParam": { "name": "filter", "in": "query", "description": "Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).", "type": "string" }, "qQueryParam": { "name": "q", "in": "query", "description": "Optional search string. See [searching](https://developer.apiture.com/docs/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" }, "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" } }, "responses": { "204": { "description": "No Content. The resource was deleted successfully." }, "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" }, "x-apiture-errors": [ "malformedRequestBodyBadRequest" ] }, "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" }, "x-apiture-errors": [ "preconditionRequiredIfMatchHeader" ] }, "400Organization": { "description": "Bad Request. The `organization` or `organizationUri` was malformed or does not refer to an organization.", "schema": { "$ref": "#/definitions/errorResponse" } }, "404Organization": { "description": "Not Found. There is no such organization resource at the specified `{organizationId}`. The `_error` field in the response will contain details about the request error.", "schema": { "$ref": "#/definitions/errorResponse" } }, "409OrganizationConflict": { "description": "Conflict. There is no such organization resource at the specified `{organizationId}`. The `_error` field in the response will contain details about the request error. Conflict. There is a conflict between the request and the current state of the resource. It may be one of the following:\n * An organization with the associated taxId already exists\n * The `state` of a `removed` user may not be changed.\n * The `state` cannot be updated via a `PUT` or `POST` request. Please use the appropriate endpoint to change the state.\n * Some key fields of the user record may not be changed or\n removed, such as their `taxId`", "schema": { "$ref": "#/definitions/errorResponse" } } }, "definitions": { "organizationFields": { "title": "Organization Fields", "description": "Common fields of the organization resource used to build other model schemas.", "properties": { "name": { "description": "The organization's official full name", "type": "string" }, "label": { "description": "The organization's common name.", "type": "string" }, "type": { "description": "Indicates what type of organization this resource represents.
**NOTE**: This may move to a mutable `organizationTypes` configuration array", "type": "string", "enum": [ "corporation", "partnership", "llc", "llp", "nonProfit", "trust", "municipality" ] }, "subtype": { "description": "A refinement of the `type`.
**NOTE**: This may move to a mutable `organizationSubTypes` configuration array
", "type": "string", "enum": [ "soleProprietorship", "partnership", "limitedPartnership", "corporation", "sCorporation", "limitedLiabilityCompany", "revokableTrust", "irrevocableTrust", "assetProtectionTrust", "charitableTrust", "constructiveTrust", "specialNeedsTrust", "spendthriftTrust", "taxBypassTrust", "tottenTrust", "other" ] }, "identification": { "description": "A collection of official identifying information associated with the contact. This currently only supports government tax ID.", "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. `taxId` is the only supported type at this time.", "type": "string", "enum": [ "taxId", "dunsNumber" ] }, "expiration": { "description": "The date when the form of identification expires.", "type": "string", "format": "date" } } } }, "addresses": { "description": "An array of postal mailing addresses for this organization.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/address" } }, "phones": { "description": "A collection of phone numbers associated with the organization.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The type of phone number this represents.", "type": "string", "enum": [ "home", "work", "mobile", "other" ] }, "number": { "description": "The phone number, as a string.", "type": "string", "example": "555-555-5555" } } } }, "emailAddresses": { "description": "An array of email addresses associated with the organization. The first item, if present, is the default (preferred) organization email.", "type": "array", "items": { "type": "string", "format": "email" } }, "finxactId": { "type": "string" }, "state": { "description": "The state of this organization.", "type": "string", "enum": [ "pending", "inactive", "active", "merged", "removed" ] }, "tradeName": { "type": "string", "description": "The trade name of the organization." }, "establishedDate": { "description": "The date the organization was established.", "type": "string", "format": "date" }, "governmentOwned": { "description": "Indicates whether the organization is a government-owned entity.", "type": "boolean" }, "publiclyHeld": { "description": "Indicates whether the organization is publicly held.", "type": "boolean" }, "smallBusiness": { "description": "Indicates whether the organization is classified as a small business", "type": "boolean" }, "taxExempt": { "description": "Indicates whether the organization is the tax-exempt.", "type": "boolean" }, "employeeCountLowerBound": { "description": "The lower bound of persons employed.", "type": "number", "minimum": 1 }, "employeeCountUpperBound": { "description": "The upper bound of persons employed.", "type": "number", "maximum": 20000000 }, "homeUrl": { "description": "The organization's home page.", "type": "string" }, "industry": { "description": "Indicates what industry does this organization work within.", "type": "string" }, "countryOfOperations": { "type": "string", "description": "The ISO 3166-1 country code for the organization's operation.", "minLength": 2, "maxLength": 2 }, "regulatory": { "description": "An object containing answers to organization specific regulatory questions.", "type": "object" }, "currency": { "description": "The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for this monetary value. This is always upper case ASCII. TODO: ISO 4217 defines three-character codes. However, ISO 4217 does not account for cryptocurrencies. Of note, DASH uses 4 characters.", "type": "string", "minLength": 3, "maxLength": 3 }, "estimatedAnnualRevenue": { "description": "Dollar amount of estimated revenue.", "type": "string" }, "mobileCheckDepositEnabled": { "description": "Indicates that the organization use mobile check deposits.", "type": "boolean" }, "achEnabled": { "description": "Indicates that the organization use ACH transfers.", "type": "boolean" }, "estimatedMonthlyAmounts": { "type": "object", "description": "Indicates the estimated monthly amounts for wires, mobile deposits and ACH", "properties": { "sentWire": { "description": "Indicates the estimated monthly minimum wires amount sent.", "type": "string" }, "receivedWire": { "description": "Indicates the estimated monthly minimum wires amount received.", "type": "string" }, "mobileCheckDeposit": { "description": "Indicates the estimated monthly minimum amount to deposit.", "type": "string" }, "receivedAch": { "description": "Indicates the estimated monthly total amount to receive by ACH.", "type": "string" }, "sentAch": { "description": "Indicates the estimated monthly total amount to send by ACH.", "type": "string" } } } }, "example": { "name": "Smith's Auto Detailing", "label": "Smith's Detailing", "emailAddresses": [ "smitties-detailing@example.com" ], "phones": [ { "type": "work", "number": "(555) 555-5555" }, { "type": "mobile", "number": "(999) 555-5555" } ], "addresses": [ { "type": "work", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" }, { "type": "work", "addressLine1": "123 S 3rd Street", "addressLine2": "Apt 42", "city": "Wilmington", "regionCode": "NC", "postalCode": "28411-5405", "countryCode": "US" } ], "state": "active", "currency": "USD", "estimatedAnnualRevenue": "125000.51", "estimatedMonthlyAmounts": { "sentWire": "20000.00", "receivedWire": "30000.00", "mobileCheckDeposit": "250000.00", "receivedAch": "40000.00", "sentAch": "35000.00" } } }, "address": { "title": "Address", "description": "A postal address.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "home", "work", "school", "other" ] }, "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 }, "addressId": { "description": "Identifier for address in finxact" } }, "example": { "type": "home", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" } }, "createOrganization": { "title": "Create Organization", "description": "Representation used to create a new organization.", "required": [ "name" ], "allOf": [ { "$ref": "#/definitions/abstractResource" }, { "$ref": "#/definitions/organizationFields" }, { "type": "object", "properties": { "attributes": { "type": "object", "description": "An optional map of name/value pairs which provide additional metadata about the organization." } } } ], "example": { "_profile": "http://api.apiture.com/schemas/basePath/organization/v1.0.0/profile.json" } }, "summaryOrganization": { "title": "Organization Summary", "description": "Summary representation of an organization resource in organizations 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" }, { "$ref": "#/definitions/organizationFields" }, { "type": "object", "properties": { "_id": { "description": "The unique identifier for this organization resource. This is an immutable opaque string.", "type": "string" } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/organizations/organization/v1.0.0/profile.json", "_links": { "self": { "href": "/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c" } } } }, "updateOrganization": { "title": "Update Organization", "description": "Representation used to update or patch an organization.", "allOf": [ { "$ref": "#/definitions/summaryOrganization" }, { "type": "object", "properties": { "attributes": { "type": "object", "description": "An optional map of name/value pairs which provide additional metadata about the organization." } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/organizations/organization/v1.0.0/profile.json" } }, "organization": { "title": "Organization", "description": "Representation of content and descriptive data (mailing addresses, phone numbers, email addresses) for an organization. An organization may have the following links in the `_links` object:\n * **`apiture:activate`** - Activate a new, pending organization\n * **`apiture:deactivate`** - Deactivate an organization (if it\n is active)\n * **`apiture:remove`** - Remove an inactive organization", "allOf": [ { "$ref": "#/definitions/updateOrganization" }, { "type": "object", "properties": { "createdAt": { "description": "The date-time when the organization was created.", "type": "string", "format": "date-time" }, "updatedAt": { "description": "The date-time when the organization was updated", "type": "string", "format": "date-time" } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/organizations/organization/v0.1.0/profile.json", "createdAt": "2018-04-17T10:04:46.375Z", "updatedAt": "2018-04-17T10:12:58.375Z", "_links": { "self": { "href": "/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c" }, "apiture:deactivate": { "href": "/organizations/inactiveOrganizations?organization=0399abed-fd3d-4830-a88b-30f38b8a365c" } }, "_embedded": {} } }, "organizations": { "title": "Organization Collection", "description": "Collection of organizations. The items in the collection are ordered in the `_embedded.items` array; the `name` is `organizations`.\n The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)\n ", "allOf": [ { "$ref": "#/definitions/collection" }, { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "items": { "description": "An array containing a page of organization items.", "type": "array", "items": { "$ref": "#/definitions/summaryOrganization" } } } } } } ], "example": { "_profile": "http://api.apiture.com/schemas/organizations/organizations/v0.1.0/profile.json", "start": 10, "limit": 10, "count": 67, "name": "organizations", "_links": { "self": { "href": "/organizations/organizations?start=10&limit=10" }, "first": { "href": "/organizations/organizations?start=0&limit=10" }, "next": { "href": "/organizations/organizations?start=20&limit=10" }, "collection": { "href": "/organizations/organizations" } }, "_embedded": { "items": [ { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/organizations/organization/v0.1.0/profile.json", "_links": { "self": { "href": "/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c" } }, "firstName": "John", "middleName": "Daniel", "lastName": "Smith", "preferredName": "John", "identification": [ { "value": "111-11-1111", "type": "taxId" } ], "emailAddresses": [ "api@apiture.com", "support@apiture.com" ], "phones": [ { "type": "home", "number": "(555) 555-5555" }, { "type": "mobile", "number": "(999) 555-5555" } ], "birthdate": "1974-10-27", "citizenship": [ { "countryCode": "US", "status": "citizen" } ], "occupation": "Software Engineer", "addresses": [ { "type": "home", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" }, { "type": "work", "addressLine1": "123 S 3rd Street", "addressLine2": "Apt 42", "city": "Wilmington", "regionCode": "NC", "postalCode": "28411-5405", "countryCode": "US" } ], "state": "active" } ] } } }, "abstractResource": { "x-apiture-version": "1.0.0", "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/schema/example/v1.0.0/profile.json", "_links": { "self": { "href": "{uri of current resource}" } } }, "properties": { "_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" } }, "_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](https://developer.apiture.com//docs/concepts/profiles) 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": { "x-apiture-version": "1.0.0", "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": "1.0.0", "_profile": "https://api.apiture.com/schemas/common/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": { "x-apiture-version": "1.0.0", "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": { "x-apiture-version": "1.0.0", "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": { "x-apiture-version": "1.0.0", "title": "Attributes", "description": "An optional map of name/value pairs which contains additional dynamic data about the resource.", "type": "object" }, "link": { "x-apiture-version": "1.0.0", "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." } } }, "collection": { "x-apiture-version": "1.0.0", "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" } } } ] } }, "x-apiture-traits": [ { "api": { "title": "Organizations", "basePath": "organizations", "links": [ "getApiDoc", "getOrganizations", "createOrganization" ] } }, { "resource": { "name": "organization", "description": "Organization data (mailing addresses, phone numbers, email addresses) for an organization (business, non-profit, trust).", "excludeMethods": [ "delete" ] } } ], "x-apiture-errors": { "malformedRequestBodyBadRequest": { "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" }, "preconditionRequiredIfMatchHeader": { "description": "The required if-match header was not supplied", "remediation": "Send a valid if-match header" } } }