# Staircase — full corpus
# Agents
# Agents
The tool registry a client connects to, and the fleet itself — every agent listed by what it does.
The roster files every agent under the dimension it works on — the same ones the navigation runs on, plus the router and the agents that build other agents. The router is the way in: nobody memorises the roster, a task is described in plain language, and the router names the specialist and the skills that fit.
An agent that changes production behaviour shows its work before acting: a comparison over sample records, a dry run, and a human approval gate on the consequential step.
-
## The network
- Key services are documented well enough that an agent can rebuild them from scratch. The documentation is the system of record, which is what keeps it honest and current.
- Building agents encode how a reliable service gets constructed, so each new runtime agent is assembled from proven patterns rather than designed from nothing. The cost of adding the next agent keeps falling.
- An agent that touches production behaviour shows its work first — before-and-after comparisons, dry runs, and human approval gates — so people stay in control of every consequential decision.
- Business users launch pipelines, change rules, request exports, and manage copy by writing plain-language requests, work that previously required an engineer running scripts.
- Because specialists share the same skills and standards, services built years apart still look and behave like siblings — easier to operate, audit, and hand over.
-
## Skills
- Packaged, versioned know-how — how to integrate a partner, how to model data, how to test a design — that any agent or engineer picks up. Knowledge is written once and reused everywhere, so it compounds instead of evaporating when a person leaves or a system changes.
-
## Registry
- One index of every agent and skill, deliberately repository-agnostic: each row names the repository that defines it, so specialists authored in different packages sit side by side in one place. Nobody memorises the roster — describe the task and the router names the specialist.
-
## Tools
- One tool registry is the single source both transports read, so the stdio entry and the HTTP entry cannot drift apart.
- Every tool carries a title, a description, and a per-parameter description written for a model rather than for a reader who already knows the domain.
- Query tools are guarded in four layers: comment and literal stripping, multi-statement rejection, a read-only statement allowlist, and an unconditional row cap.
-
## Fleet
- Agent definitions are compiled from one source into three runtimes, so a behaviour change is written once and lands everywhere.
- A router dispatches to specialists rather than one agent carrying every capability.
- Skills are separately versioned units an agent composes, not prompt text pasted into a definition.
-
## Evaluations
- Behavioural fixtures assert exact tool-call arguments, not output similarity, and they run in continuous integration before a deploy.
- A conversational agent that stops calling the right tool fails the build rather than degrading quietly once deployed.
- Per-conversation model cost is reported to a budget surface, so an agent that becomes expensive is visible as a number.
-
## Runtimes
- The same registry is served over a standard-input transport, a streaming HTTP transport, and an edge runtime.
- Documented, working install paths exist for five separate agent clients — this is a multi-client surface, not a single-vendor integration.
- Configuration is environment-supplied, so pointing the surface at a different set of jurisdictions is a configuration change rather than a release.
## Routing
The way into the fleet: one agent reads a request and hands it to the specialist that owns the work.
- Router
Reads the current roster and names which specialist and which skills fit the task, with the reasoning behind the choice.
## Data
The records, the schema over them, and what is read back out — ingestion, retrieval, reporting, reconciliation and extracts.
- Counterparty document expectations
Loads counterparty contact details and document requirements from spreadsheets into the graph store, mapping each requirement onto the governed vocabulary and setting aside anything that does not map.
- Data-lake assistant
Answers questions over the accumulated loan and partner data in plain language, and draws the chart where a chart is the answer.
- Dataset fulfilment
Turns an approved data request into a scoped extract — resolving which organisation it belongs to, mapping the requested field names onto the canonical model, and returning either the result directly or a time-limited download link.
- Knowledge search
Builds reusable retrieval agents that answer from a curated document corpus — embeddings, a search index, a knowledge library, schema and header mapping, reuse of prior decisions, confidence thresholds and a human review loop.
- Metric reconciliation
Reconciles the same metric across vendors and sources so the figures compare like with like, and records why they differed.
- Model curator
Guards the shared graph schema, so that every entity type, relationship, property, index, enumeration and required field passes one review and ingestion and query behaviour stay consistent across services.
- Pipeline control panel
Runs the document-processing pipeline on request: resolves which documents actually exist for a set of records, checks what has already been processed, dispatches only the remainder, replays failures, and confirms the results reached their destination.
- Property data exploration
Answers questions about public property and business data in plain language — appraisal and parcel records, permits, registered companies, contractor reputation, geographic filters and the schema behind them — by driving the published tool surface rather than writing queries by hand.
- Public record ingestion
Brings a jurisdiction's public data online: discovers the sources, collects and validates them, loads and reconciles them into the query store, then publishes the jurisdiction's query table and coverage record and wires both into the tool surface.
- Question answering
Resolves which approved source actually holds a figure, queries it live, and turns the verified answer into a secure, shareable, refreshing report.
- Report catalog
Builds and maintains the single page where existing reports are registered and found, with a command-line path for registering a new one.
- Search to production
Takes a retrieval system from a local prototype through to production: the index model, the migration off the local store, historical backfill, live ingestion per source, and the instructions an agent needs to use it.
## Products
The borrower conversation and the assistants around it, collecting the credit, assets, liabilities, employment, income and real estate owned that the Products dimension documents.
- Application document
Generates the completed application document from everything the conversation collected, and takes the borrower's signature on it.
- Assets
Collects what the borrower holds — deposit and investment accounts, the institution each sits with, and the balance.
- Co-borrower invitation
Invites a co-borrower into the application and starts their own task set, which is the borrower's set plus the questions only they can answer.
- Contact details
Collects how to reach the borrower — telephone numbers by kind, and the electronic-mail address the application and its documents are sent to.
- Correction
Reopens a subject the borrower has already answered so an answer can be changed without restarting the application.
- Credit
Takes the borrower's consent to a credit enquiry, runs it, and brings the result back into the conversation so the liabilities it reports can be confirmed rather than typed.
- Declarations
Collects the declaration questions the application requires, and the follow-up detail wherever an answer needs one.
- Demographic details
Collects the regulated demographic questions, including the borrower's right to decline each of them.
- Employment and income
Collects employment and the income that comes from it — employer, role, dates, and the pay in the components a lender underwrites: base, overtime, bonus and commission.
- Frequently-asked questions
Answers a borrower's questions from a curated knowledge base rather than from the model's general knowledge, with the source behind each answer.
- Gifts and grants
Collects funds given to the borrower rather than held by them — the donor, the relationship, the amount, and whether the funds have arrived.
- Liabilities
Reviews the debts the credit enquiry reported, corrects them, and collects the ones it did not — the obligations that do not appear on a credit file.
- Loan lookup
Finds an existing application from what the borrower can remember, so a returning conversation resumes rather than restarts.
- Military service
Collects service history, which decides eligibility for the loan programmes that depend on it.
- Mortgage details
Collects the terms of the loan being applied for and of any mortgage already secured on a property the borrower owns — amount, purpose, occupancy and term.
- Other income
Collects income from every source that is neither employment nor a business the borrower owns — rental income, benefits, pensions, investments, support payments.
- Personal identity
Opens the application and collects who the borrower is — legal name, date of birth, taxpayer identifier, citizenship and marital status.
- Preapproval letter
Produces the preapproval letter from the priced application, and refreshes it when the price behind it moves.
- Pricing
Runs an actual price against the collected loan terms and explains the result in the conversation.
- Rate estimate
Gives a borrower an indicative rate from a short conversation, before any application exists.
- Real estate owned
Collects the properties the borrower already owns — address, value, how it is used, and what it earns or costs.
- Residency
Collects where the borrower lives now and where they lived before, with the dates, so the address history covers the required period without gaps.
- Self-employment income
Collects income from a business the borrower owns, including contract income reported on its own tax form.
- Workspace assistant
The assistant inside the internal workspace: answers a reviewer's questions about an application in progress and drafts the message going back to the borrower.
## Providers
A vendor integration or a counterparty exchange — a message provider's send-and-feedback loop, a partner's file share, a partner's client list, a third-party measurement console.
- File sync
Builds the scheduled workflow that copies a configured storage location into an external partner's file share: the infrastructure, a planning and cost gate, per-file workers, an aggregate, and the credential and configuration handling around them.
- Marketing stack
Orchestrates the whole measurement stack across consoles and code — tag management, analytics, search visibility, advertising linkage, the access each of those needs, and the handoff to whoever verifies it.
- Roster workflow
Takes each partner's uploaded client list, matches it against the records under management, and returns partner-branded settlement and authorisation paperwork the same day.
- Send lifecycle
Owns the whole dispatch and feedback loop as one lifecycle: provider setup, routing, the send handoff, delivery events, and ingestion of what comes back.
## Delivery
Software being built, packaged, released, deployed or tested — scaffolding an application, distributing it to tenants, implementing a design, triaging what renders wrongly.
- Analytics instrumentation
Wires tag management into a front end on any of the common frameworks, and works out with the team which user actions are worth tracking.
- Application scaffolding
Scaffolds complete applications on the standard stack, front end and back end together in one repository, with the shared packages between them.
- Design implementation
Translates a design into existing interface code, preserving the business logic underneath and locking in the breakpoints.
- Design testing
Writes the tests that verify an interface renders correctly across phone, tablet and desktop, in whichever of the two lanes fits — mocked specifications for the design itself, or real-device specifications for behaviour.
- Interface triage
Triages and fixes interface defects: confirms the delta against the design reference, audits recent commits for the override that caused it, applies the smallest correcting change, and strengthens the tests so it cannot return.
- Marketplace architecture
Architects the multi-tenant platform through which products are packaged, distributed and installed — a central account governing per-customer accounts, a registry of components and releases, and the four ecosystem products underneath it: domain routing, account management, the product deployer and the tenant-side reconciler.
- Sharing portals
Builds secure external file-sharing portals: hosted sign-in, private folder browsing, per-user grants, administrator-managed accounts, a custom domain, runtime configuration and a design-matched interface.
## Platform
What runs underneath: the conversation runtime and its queue, batch workflows, solvers, short links, template inventory, campaign operations and the capability map.
- Audience selection
Defines who a communication goes to, owning the entry point, the hard suppressions, and the contract by which an eligible population is handed to the runtime that will act on it.
- Batch workflows
Designs large-scale batch and extract-transform-load workflows with cost gates, throttling, idempotency and a staged test path.
- Capability map
Knows every internal platform capability — accounts, bootstrap, build, distribution, deployment, reconciliation, persistence, connectivity, translation, product orchestration, rule decisioning and the governed vocabulary — and decides whether a request is served by something already deployed before any infrastructure is written.
- Channel assembly
Composes audience, template and send capabilities into one deterministic end-to-end channel service — the internal data contracts, candidate generation, scoring, allocation, outputs and runtime validation.
- Contact scheduling solver
Holds how one deployed scheduling solver actually works — how it prioritises records, selects a contact point, respects capacity, assigns hours, rotates between contact points and labels score tiers — and extends it without inventing a parallel runtime.
- Conversation management
Manages the fleet around the runtime: the queue a conversation waits in, the configuration each agent runs from, and the tasks raised for a person when a conversation needs one.
- Conversation runtime
Serves the conversation itself: holds the task set, runs the agent whose turn it is, calls the functions an answer triggers, and writes what was said to the loan record.
- Mail campaign operations
Operates the deployed mail-campaign workflow: validating the population for a run, launching it, watching it, and reconciling what came back against what was sent.
- Message assistant
Answers questions about what has been sent to a consumer, and lets a non-technical user propose, revise, or retire a message template through a plain-language review conversation that captures the approved wording.
- Rule editor
Turns a plain-language request into a concrete change to phone-interaction rules, runs it against sample records to show exactly which numbers would and would not be called, and packages that before-and-after evidence for the rule owner to approve.
- Short links
Builds the link-shortening and click-telemetry service behind outbound messages: issuing short tokens, storing the link as a graph record, resolving a token through a graph query, redirecting, and publishing a click fact onto the shared event bus.
- Solver services
Designs and scaffolds optimisation services: a distributed layer that prepares data at scale, a pure solver core, and the infrastructure that wires them together.
- Template inventory
Builds the systems that keep message templates versioned, reviewed and in step with whatever sends them — the repository layout, the metadata contract, discovery of the source tables, and one-time or recurring synchronisation from the operational store into a version-controlled inventory.
## Creating new agents
Agents whose output is another agent — the specification it is written from, the scaffold it is built on, and the evaluation set that gates it.
- Assistant builder
Designs and implements task-triggered agents on the established runtime pattern — one function receiving events from the work-management surface, conversation state held externally, a model doing the reasoning, and tracing on every turn.
- Audit analyser
Builds analysers that read pipeline output, apply versioned audit profiles, and emit evidence-backed anomaly records for a person to review.
- Operations agent builder
Builds the operations agents that drive document and media pipelines: resolving the target environment from what the requester said or from their profile, discovering the deployed stack, starting and watching runs, handling replays and approval gates, and preparing configuration changes as reviewable proposals.
- Spend approval
Builds the workflow that watches model spend against a threshold, opens an approval task when it is crossed, and raises the limit by a configured increment only after a human completes that task.
---
# Creating new agents
# Creating new agents
Agents whose output is another agent — the specification it is written from, the scaffold it is built on, and the evaluation set that gates it.
- Assistant builder
Designs and implements task-triggered agents on the established runtime pattern — one function receiving events from the work-management surface, conversation state held externally, a model doing the reasoning, and tracing on every turn.
- Audit analyser
Builds analysers that read pipeline output, apply versioned audit profiles, and emit evidence-backed anomaly records for a person to review.
- Operations agent builder
Builds the operations agents that drive document and media pipelines: resolving the target environment from what the requester said or from their profile, discovering the deployed stack, starting and watching runs, handling replays and approval gates, and preparing configuration changes as reviewable proposals.
- Spend approval
Builds the workflow that watches model spend against a threshold, opens an approval task when it is crossed, and raises the limit by a configured increment only after a human completes that task.
---
# Data
# Data
The records, the schema over them, and what is read back out — ingestion, retrieval, reporting, reconciliation and extracts.
- Counterparty document expectationsalso Providers
Loads counterparty contact details and document requirements from spreadsheets into the graph store, mapping each requirement onto the governed vocabulary and setting aside anything that does not map.
- Data-lake assistant
Answers questions over the accumulated loan and partner data in plain language, and draws the chart where a chart is the answer.
- Dataset fulfilment
Turns an approved data request into a scoped extract — resolving which organisation it belongs to, mapping the requested field names onto the canonical model, and returning either the result directly or a time-limited download link.
- Knowledge search
Builds reusable retrieval agents that answer from a curated document corpus — embeddings, a search index, a knowledge library, schema and header mapping, reuse of prior decisions, confidence thresholds and a human review loop.
- Metric reconciliation
Reconciles the same metric across vendors and sources so the figures compare like with like, and records why they differed.
- Model curator
Guards the shared graph schema, so that every entity type, relationship, property, index, enumeration and required field passes one review and ingestion and query behaviour stay consistent across services.
- Pipeline control panel
Runs the document-processing pipeline on request: resolves which documents actually exist for a set of records, checks what has already been processed, dispatches only the remainder, replays failures, and confirms the results reached their destination.
- Property data exploration
Answers questions about public property and business data in plain language — appraisal and parcel records, permits, registered companies, contractor reputation, geographic filters and the schema behind them — by driving the published tool surface rather than writing queries by hand.
- Public record ingestion
Brings a jurisdiction's public data online: discovers the sources, collects and validates them, loads and reconciles them into the query store, then publishes the jurisdiction's query table and coverage record and wires both into the tool surface.
- Question answering
Resolves which approved source actually holds a figure, queries it live, and turns the verified answer into a secure, shareable, refreshing report.
- Report catalog
Builds and maintains the single page where existing reports are registered and found, with a command-line path for registering a new one.
- Search to production
Takes a retrieval system from a local prototype through to production: the index model, the migration off the local store, historical backfill, live ingestion per source, and the instructions an agent needs to use it.
---
# Delivery
# Delivery
Software being built, packaged, released, deployed or tested — scaffolding an application, distributing it to tenants, implementing a design, triaging what renders wrongly.
- Analytics instrumentationalso Providers
Wires tag management into a front end on any of the common frameworks, and works out with the team which user actions are worth tracking.
- Application scaffolding
Scaffolds complete applications on the standard stack, front end and back end together in one repository, with the shared packages between them.
- Design implementation
Translates a design into existing interface code, preserving the business logic underneath and locking in the breakpoints.
- Design testing
Writes the tests that verify an interface renders correctly across phone, tablet and desktop, in whichever of the two lanes fits — mocked specifications for the design itself, or real-device specifications for behaviour.
- Interface triage
Triages and fixes interface defects: confirms the delta against the design reference, audits recent commits for the override that caused it, applies the smallest correcting change, and strengthens the tests so it cannot return.
- Marketplace architecture
Architects the multi-tenant platform through which products are packaged, distributed and installed — a central account governing per-customer accounts, a registry of components and releases, and the four ecosystem products underneath it: domain routing, account management, the product deployer and the tenant-side reconciler.
- Sharing portalsalso Providers
Builds secure external file-sharing portals: hosted sign-in, private folder browsing, per-user grants, administrator-managed accounts, a custom domain, runtime configuration and a design-matched interface.
---
# Evaluations
# Evaluations
Behavioural fixtures asserting exact tool-call arguments, run before a deploy.
A fixture states the input and the tool call that must result, with its exact arguments. It does not compare output text, because output similarity passes while the agent calls the wrong tool with plausible arguments — which is the failure that matters.
The fixtures run in continuous integration before a deploy, so an agent that stops calling the right tool fails the build rather than degrading quietly once deployed.
- Behavioural fixtures assert exact tool-call arguments, not output similarity, and they run in continuous integration before a deploy.
- A conversational agent that stops calling the right tool fails the build rather than degrading quietly once deployed.
- Per-conversation model cost is reported to a budget surface, so an agent that becomes expensive is visible as a number.
## How it works
Cost is reported per conversation against a budget surface, which makes an agent that has become expensive visible as a number rather than as a surprise on an invoice. The budget it reports against is the per-environment one in Environment.
---
# Fleet
# Fleet
One agent source compiled to three runtimes, dispatched by a router, composed from separately versioned skills.
An agent is defined once and compiled into each runtime it needs to run in, so a behaviour change is written in one place and lands everywhere. The alternative — a definition per runtime — drifts within weeks and drifts silently.
Dispatch is by router rather than by one agent carrying every capability. A specialist with a narrow scope is easier to evaluate, easier to fix, and easier to reason about than a general agent whose behaviour depends on which part of a long instruction won.
- Agent definitions are compiled from one source into three runtimes, so a behaviour change is written once and lands everywhere.
- A router dispatches to specialists rather than one agent carrying every capability.
- Skills are separately versioned units an agent composes, not prompt text pasted into a definition.
---
# The network
# The network
Three layers: agents that operate production systems, agents that build them, and the skills both draw on.
Key services are documented well enough that an agent can rebuild them from scratch. The documentation is the system of record, which is what keeps it honest and current.
The runtime layer is deployed services holding their own memory and telemetry, invoked by external events and operated through the tools a team already has open. The building layer lives in the engineering environment and designs, scaffolds and reviews software — several of its members exist to build runtime agents, which is what makes the network self-expanding. Skills are the packaged know-how both layers draw on.
The registry is the index across all three.
## How it works
A building agent encodes how a reliable service is constructed, so the next runtime agent is assembled from patterns that already worked rather than designed from nothing, and the cost of the next one keeps falling.
Each layer is specified to the level a rebuild needs: a service that cannot be rebuilt from its own specification is one whose specification is not exercised, and a gap in it shows up as a rebuild that does not work.
## Three layers
| Layer | What it is |
| --- | --- |
| Runtime agents | Long-running deployed services that operate on production systems. They hold their own memory and telemetry, are invoked by external events, and are used through the tools an operations team already has open — no engineering involvement to run one. |
| Building agents | Specialists that live in the engineering environment and help design, scaffold, and review software. Several exist specifically to build new runtime agents, which is what makes the network self-expanding. |
| Skills | Packaged, versioned know-how — how to integrate a partner, how to model data, how to test a design — that any agent or engineer picks up. Knowledge is written once and reused everywhere, so it compounds instead of evaporating when a person leaves or a system changes. |
## The loop
1. A need surfaces in plain language.
1. The router sends it to the right building agents, which pull in the relevant skills.
1. Those agents assemble a new runtime agent from proven patterns.
1. The runtime agent is deployed, used through the tools the team already has open, and registered.
1. Whatever was learned is captured as a skill, making the next agent cheaper to build.
## What holds it together
- **Agents that build agents** — Building agents encode how a reliable service gets constructed, so each new runtime agent is assembled from proven patterns rather than designed from nothing. The cost of adding the next agent keeps falling.
- **Evidence before action** — An agent that touches production behaviour shows its work first — before-and-after comparisons, dry runs, and human approval gates — so people stay in control of every consequential decision.
- **Operations through conversation** — Business users launch pipelines, change rules, request exports, and manage copy by writing plain-language requests, work that previously required an engineer running scripts.
- **Consistency at scale** — Because specialists share the same skills and standards, services built years apart still look and behave like siblings — easier to operate, audit, and hand over.
---
# Platform
# Platform
What runs underneath: the conversation runtime and its queue, batch workflows, solvers, short links, template inventory, campaign operations and the capability map.
- Audience selectionalso Data
Defines who a communication goes to, owning the entry point, the hard suppressions, and the contract by which an eligible population is handed to the runtime that will act on it.
- Batch workflows
Designs large-scale batch and extract-transform-load workflows with cost gates, throttling, idempotency and a staged test path.
- Capability map
Knows every internal platform capability — accounts, bootstrap, build, distribution, deployment, reconciliation, persistence, connectivity, translation, product orchestration, rule decisioning and the governed vocabulary — and decides whether a request is served by something already deployed before any infrastructure is written.
- Channel assembly
Composes audience, template and send capabilities into one deterministic end-to-end channel service — the internal data contracts, candidate generation, scoring, allocation, outputs and runtime validation.
- Contact scheduling solver
Holds how one deployed scheduling solver actually works — how it prioritises records, selects a contact point, respects capacity, assigns hours, rotates between contact points and labels score tiers — and extends it without inventing a parallel runtime.
- Conversation management
Manages the fleet around the runtime: the queue a conversation waits in, the configuration each agent runs from, and the tasks raised for a person when a conversation needs one.
- Conversation runtime
Serves the conversation itself: holds the task set, runs the agent whose turn it is, calls the functions an answer triggers, and writes what was said to the loan record.
- Mail campaign operations
Operates the deployed mail-campaign workflow: validating the population for a run, launching it, watching it, and reconciling what came back against what was sent.
- Message assistant
Answers questions about what has been sent to a consumer, and lets a non-technical user propose, revise, or retire a message template through a plain-language review conversation that captures the approved wording.
- Rule editor
Turns a plain-language request into a concrete change to phone-interaction rules, runs it against sample records to show exactly which numbers would and would not be called, and packages that before-and-after evidence for the rule owner to approve.
- Short links
Builds the link-shortening and click-telemetry service behind outbound messages: issuing short tokens, storing the link as a graph record, resolving a token through a graph query, redirecting, and publishing a click fact onto the shared event bus.
- Solver services
Designs and scaffolds optimisation services: a distributed layer that prepares data at scale, a pure solver core, and the infrastructure that wires them together.
- Template inventory
Builds the systems that keep message templates versioned, reviewed and in step with whatever sends them — the repository layout, the metadata contract, discovery of the source tables, and one-time or recurring synchronisation from the operational store into a version-controlled inventory.
---
# Products
# Products
The borrower conversation and the assistants around it, collecting the credit, assets, liabilities, employment, income and real estate owned that the Products dimension documents.
- Application document
Generates the completed application document from everything the conversation collected, and takes the borrower's signature on it.
- Assets
Collects what the borrower holds — deposit and investment accounts, the institution each sits with, and the balance.
- Co-borrower invitation
Invites a co-borrower into the application and starts their own task set, which is the borrower's set plus the questions only they can answer.
- Contact details
Collects how to reach the borrower — telephone numbers by kind, and the electronic-mail address the application and its documents are sent to.
- Correction
Reopens a subject the borrower has already answered so an answer can be changed without restarting the application.
- Credit
Takes the borrower's consent to a credit enquiry, runs it, and brings the result back into the conversation so the liabilities it reports can be confirmed rather than typed.
- Declarations
Collects the declaration questions the application requires, and the follow-up detail wherever an answer needs one.
- Demographic details
Collects the regulated demographic questions, including the borrower's right to decline each of them.
- Employment and income
Collects employment and the income that comes from it — employer, role, dates, and the pay in the components a lender underwrites: base, overtime, bonus and commission.
- Frequently-asked questions
Answers a borrower's questions from a curated knowledge base rather than from the model's general knowledge, with the source behind each answer.
- Gifts and grants
Collects funds given to the borrower rather than held by them — the donor, the relationship, the amount, and whether the funds have arrived.
- Liabilities
Reviews the debts the credit enquiry reported, corrects them, and collects the ones it did not — the obligations that do not appear on a credit file.
- Loan lookup
Finds an existing application from what the borrower can remember, so a returning conversation resumes rather than restarts.
- Military service
Collects service history, which decides eligibility for the loan programmes that depend on it.
- Mortgage details
Collects the terms of the loan being applied for and of any mortgage already secured on a property the borrower owns — amount, purpose, occupancy and term.
- Other income
Collects income from every source that is neither employment nor a business the borrower owns — rental income, benefits, pensions, investments, support payments.
- Personal identity
Opens the application and collects who the borrower is — legal name, date of birth, taxpayer identifier, citizenship and marital status.
- Preapproval letter
Produces the preapproval letter from the priced application, and refreshes it when the price behind it moves.
- Pricing
Runs an actual price against the collected loan terms and explains the result in the conversation.
- Rate estimate
Gives a borrower an indicative rate from a short conversation, before any application exists.
- Real estate owned
Collects the properties the borrower already owns — address, value, how it is used, and what it earns or costs.
- Residency
Collects where the borrower lives now and where they lived before, with the dates, so the address history covers the required period without gaps.
- Self-employment income
Collects income from a business the borrower owns, including contract income reported on its own tax form.
- Workspace assistant
The assistant inside the internal workspace: answers a reviewer's questions about an application in progress and drafts the message going back to the borrower.
---
# Providers
# Providers
A vendor integration or a counterparty exchange — a message provider's send-and-feedback loop, a partner's file share, a partner's client list, a third-party measurement console.
- File sync
Builds the scheduled workflow that copies a configured storage location into an external partner's file share: the infrastructure, a planning and cost gate, per-file workers, an aggregate, and the credential and configuration handling around them.
- Marketing stackalso Delivery
Orchestrates the whole measurement stack across consoles and code — tag management, analytics, search visibility, advertising linkage, the access each of those needs, and the handoff to whoever verifies it.
- Roster workflow
Takes each partner's uploaded client list, matches it against the records under management, and returns partner-branded settlement and authorisation paperwork the same day.
- Send lifecycle
Owns the whole dispatch and feedback loop as one lifecycle: provider setup, routing, the send handoff, delivery events, and ingestion of what comes back.
---
# Registry
# Registry
One index of every agent and skill, with the repository that defines each.
The registry is deliberately repository-agnostic. Each row names where the specialist is defined, so agents authored in different packages sit in one index rather than in several — which is what makes the router able to dispatch across all of them.
A row carries the columns below. The index is the thing a router reads and the thing a person consults when they want to know whether a capability already exists before building it again.
- One index of every agent and skill, deliberately repository-agnostic: each row names the repository that defines it, so specialists authored in different packages sit side by side in one place. Nobody memorises the roster — describe the task and the router names the specialist.
## What a row carries
- `Mascot`
- `Agent`
- `What it does`
- `Repository`
One index of every agent and skill, deliberately repository-agnostic: each row names the repository that defines it, so specialists authored in different packages sit side by side in one place. Nobody memorises the roster — describe the task and the router names the specialist.
---
# Analytics instrumentation
# Analytics instrumentation
Delivery also Providers
Wires tag management into a front end on any of the common frameworks, and works out with the team which user actions are worth tracking.
- **Used when**
— When a site needs measurement in place and the container identifier either exists or is about to.
- **Loads first**
- The framework's own entry point, and the container identifier, supplied as configuration rather than assumed.
- **Returns**
- The files changed and why.
- How the container identifier is supplied.
- How to verify the tag fires on a cold load and on client-side navigation.
- The checklist for the person who owns the analytics and advertising accounts.
- Where event discovery was asked for: the candidate list, the decisions taken, and which approved events were implemented.
- **Hands off**
- Marketing stack — the order of operations and the console-side setup across the marketing stack
## Others in Delivery
- Application scaffolding
- Design implementation
- Design testing
- Interface triage
- Marketplace architecture
- Sharing portals
---
# Application document
# Application document
Products
Generates the completed application document from everything the conversation collected, and takes the borrower's signature on it.
- **Used when**
— At the end of the task set, once every required subject is answered.
- **Collects**
- The signature, and the record of who signed and when.
- **Returns**
- The generated application document, and the standards-format export beside it.
- The signature record against the loan.
- **Evidence**
- `bot-1003-document`
- `bot-1003-sign`
- `start-loan-application-api_calls`
- `start-loan-application-taskset`
## Others in Products
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Application scaffolding
# Application scaffolding
Delivery
Scaffolds complete applications on the standard stack, front end and back end together in one repository, with the shared packages between them.
- **Used when**
— When a new application needs both halves and the boundary between them is the decision that matters.
- **Loads first**
- The front-end and back-end skill.
- The shared engineering guidelines.
- **Returns**
- The repository layout.
- The front-end and back-end boundary decisions.
- The shared package plan.
- The deployment and verification plan.
- **Hands off**
- Design implementation — translating a design into existing interface code
- Design testing — tests that verify an interface across screen sizes
## Others in Delivery
- Analytics instrumentation
- Design implementation
- Design testing
- Interface triage
- Marketplace architecture
- Sharing portals
---
# Assets
# Assets
Products
Collects what the borrower holds — deposit and investment accounts, the institution each sits with, and the balance.
- **Used when**
— After income, since the deposit and the reserves are read against it.
- **Collects**
- Each account, its kind, the institution and the balance.
- Assets that are not accounts, through the other-asset variant.
- **Returns**
- One record per asset, typed so the deposit and the reserve calculation can read them.
- **Hands off**
- Gifts and grants — funds given to the borrower rather than held by them
- **Evidence**
- `bot-asset-collector`
- `bot-assets-collector`
- `bot-other-asset-collector`
## Others in Products
- Application document
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Assistant builder
# Assistant builder
Creating new agents
Designs and implements task-triggered agents on the established runtime pattern — one function receiving events from the work-management surface, conversation state held externally, a model doing the reasoning, and tracing on every turn.
- **Used when**
— When a new agent should be triggered by a task or a comment rather than run by hand, which is the shape behind most of the deployed fleet.
- **Loads first**
- The agent-building skill, for the runtime, state and telemetry patterns.
- The shared engineering guidelines.
- **Returns**
- The architecture and its runtime boundaries — one function, its handlers, the external state layout.
- An implementation checklist covering ingress wiring, state, the webhook construct, memory, the model and its tools, and tracing.
- Deployment and configuration requirements, including the exact values a human must collect and who owns the webhook per environment.
- End-to-end verification steps covering the task flow, the traces, the locking and the persistence of conversation memory.
- **Hands off**
- Operations agent builder — operations agents for document and media pipelines
- Spend approval — approval workflows that gate model spend
- Audit analyser — analysers that scan processing output for anomalies
## Others in Creating new agents
- Audit analyser
- Operations agent builder
- Spend approval
---
# Audience selection
# Audience selection
Platform also Data
Defines who a communication goes to, owning the entry point, the hard suppressions, and the contract by which an eligible population is handed to the runtime that will act on it.
- **Used when**
— When a filter has to hand a population to a runtime, when a communication needs segmenting, or when eligibility boundaries are being drawn.
- **Loads first**
- The audience-selection skill, for the eligibility handoff and intake contract.
- The shared engineering guidelines.
- **Returns**
- The audience entry point and who owns the hard filters.
- The runtime intake contract — schema, transport, and the identifiers that travel with each record.
- The plan that makes the handoff replayable and auditable.
- Acceptance checks for the eligible population.
- **Hands off**
- Template inventory — template management
- Send lifecycle — provider delivery
- Channel assembly — runtime scoring
## Others in Platform
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Audit analyser
# Audit analyser
Creating new agents
Builds analysers that read pipeline output, apply versioned audit profiles, and emit evidence-backed anomaly records for a person to review.
- **Used when**
— When processing output needs checking against defined expectations and the result has to carry its evidence rather than a verdict.
- **Loads first**
- The agent-building and batch-workflow skills.
- The atomic-data skill, for the normalised shape the profiles run against.
- **Returns**
- The clarified input contract and any unresolved blockers.
- The recommended architecture and its runtime boundaries.
- The normalised data model.
- The audit profile catalogue, each rule with an identifier, its assumptions and its evidence requirement.
- The output contract and a sample anomaly record.
- An implementation plan, a test plan, and small-sample verification commands.
- Notes on personal data and auditability.
## Others in Creating new agents
- Assistant builder
- Operations agent builder
- Spend approval
---
# Batch workflows
# Batch workflows
Platform
Designs large-scale batch and extract-transform-load workflows with cost gates, throttling, idempotency and a staged test path.
- **Used when**
— When a job is large enough that a rerun, a rate limit or a cost surprise is the real design problem.
- **Loads first**
- The batch-workflow skill.
- The shared engineering guidelines.
- **Returns**
- The recommended architecture.
- The key assumptions and the questions still open.
- A concrete implementation plan.
- A verification plan with a small-sample path.
- **Hands off**
- Solver services — the optimisation model inside a workflow
## Others in Platform
- Audience selection
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Capability map
# Capability map
Platform
Knows every internal platform capability — accounts, bootstrap, build, distribution, deployment, reconciliation, persistence, connectivity, translation, product orchestration, rule decisioning and the governed vocabulary — and decides whether a request is served by something already deployed before any infrastructure is written.
- **Used when**
— Whenever a request touches tenancy, product distribution, deployment, graph persistence, partner integration, translation, rule decisioning, webhooks, file transfer or address allow-listing.
- **Loads first**
- The build skill and product requirements for whichever capability is in scope, re-read rather than recalled.
- The shared engineering guidelines.
- **Returns**
- Which capability the request belongs to.
- Whether an existing deployment serves it, with the evidence that settled the question.
- Either the integration path into what exists, or the provisioning plan for a new instance.
## Others in Platform
- Audience selection
- Batch workflows
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Channel assembly
# Channel assembly
Platform
Composes audience, template and send capabilities into one deterministic end-to-end channel service — the internal data contracts, candidate generation, scoring, allocation, outputs and runtime validation.
- **Used when**
— When the separate communication capabilities need to become a single service that behaves the same way twice.
- **Loads first**
- The runtime-assembly skill.
- The batch-workflow and solver skills, where allocation is an optimisation rather than a sort.
- **Returns**
- The runtime data contract and the candidate-generation plan.
- The scoring, allocation and output contracts.
- The validation and rollout plan.
- Its integration points with the three capabilities it composes.
- **Hands off**
- Audience selection — the audience entry point and its intake contract
- Template inventory — the template inventory
- Send lifecycle — provider delivery and response ingestion
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Co-borrower invitation
# Co-borrower invitation
Products
Invites a co-borrower into the application and starts their own task set, which is the borrower's set plus the questions only they can answer.
- **Used when**
— Wherever the borrower names a co-borrower, at any point in the conversation.
- **Collects**
- The co-borrower's name and electronic-mail address.
- Their consent to join the application.
- **Returns**
- The invitation sent, and a co-borrower task set opened against the same application.
- **Evidence**
- `bot-coborrower-emails`
## Others in Products
- Application document
- Assets
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Contact details
# Contact details
Products
Collects how to reach the borrower — telephone numbers by kind, and the electronic-mail address the application and its documents are sent to.
- **Used when**
— Early in the task set, before anything has to be delivered to the borrower.
- **Collects**
- Telephone numbers, by kind, with the preferred one marked.
- The electronic-mail address the application uses for delivery.
- A co-borrower's own contact details, through its variant.
- **Returns**
- The contact fields on the loan record, and a delivery address every later step can rely on.
- **Hands off**
- Co-borrower invitation — inviting a co-borrower into the application
- **Evidence**
- `bot-contact-details`
- `bot-contact-details-interactive`
- `bot-coborrower-contact-details-collector`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Contact scheduling solver
# Contact scheduling solver
Platform
Holds how one deployed scheduling solver actually works — how it prioritises records, selects a contact point, respects capacity, assigns hours, rotates between contact points and labels score tiers — and extends it without inventing a parallel runtime.
- **Used when**
— When that solver is being extended, when someone needs the prioritisation and scheduling rules explained, or when a scheduled run is being operated.
- **Loads first**
- The solver skill, whose reference documents are the authority on the business rules.
- The campaign-operation skill, when a run is being started or delivered.
- **Returns**
- Which path it took — build, explain, or operate.
- The business rules relevant to the question: contact-point selection, scoring, capacity, hours, rotation and tiers.
- For a build: architecture notes by layer, and what must stay unchanged.
- For an explanation: the generated document, grounded in the reference rules.
- For a run: the environment, the input contract, the execution identifiers and the verification evidence.
- Any drift between the written rules and the code.
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Conversation management
# Conversation management
Platform
Manages the fleet around the runtime: the queue a conversation waits in, the configuration each agent runs from, and the tasks raised for a person when a conversation needs one.
- **Used when**
— Wherever a conversation has to wait, escalate, or be picked up by someone.
- **Collects**
- The queue a conversation belongs to, and its state.
- The configuration version each agent is running.
- **Returns**
- The queue position and the state transitions.
- The task raised for a person, and the answer that closed it.
- **Evidence**
- `chatbot-queues`
- `chatbot-asana-tasks`
- `chatbot-assistant-template`
## Operations
### ChatMTG
`POST` `/functions`
#### Create Function
`createFunction`
Create a function that can be invoked by GPT in the conversation based on user input by calling a webhook URL with some values for the parameters defined in the function. Learn more about functions in the GPT documentation.
##### Request
Execute SQL QueryGet Database Schema
application/json Copy
```
{
"name": "execute_sql_query",
"description": "Use this to execute Trino SQL query using AWS Athena Engine version 3. In case of error you will get error message, you have to fix your query and try again. You can apply JOIN opperations. You should use only columns from get_database_schema function. You should use columns only for it's tables. You can join tables if needed using provided columns. You should check that column is not empty string before casting it to avoid errors like this INVALID_CAST_ARGUMENT: Cannot cast '' to BIGINT. You should never compare numbers with strings.You should NEVER call this function before get_database_schema has been called in the conversation. You should NEVER use columns names of the wrong table. You should NEVER cast comare number types to strings or char. You should ALWAYS limit query results by maximum 50. You should NEVER compare fields to NULL.",
"parameters": {
"type": "object",
"properties": {
"sql_query": {
"type": "string",
"description": "SQL query, that user asked. Table names has to be inside \"\". Subqueries are only supported for EXISTS, IN and Scalar subquery, A scalar subquery is a non-correlated subquery that returns zero or one row. It is an error for the subquery to produce more than one row. The returned value is NULL if the subquery produces no rows. Example: SELECT COUNT(*) FROM \"first-american-listings\" WHERE facalculateddaysonmarket != '' AND CAST(\"facalculateddaysonmarket\" as BIGINT) > 15. Example: {\"sql_query\": \"SELECT mtg1lender, COUNT(*) as count FROM \"table_09_fulllaunch-first-american-equity-broker-listings-assesor\" WHERE currentoriginallistingdate >= '2022-03-20' GROUP BY mtg1lender ORDER BY count DESC LIMIT 5\"}. To get current date use current_date constant"
}
},
"required": [
"sql_query"
]
},
"webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
```
application/json Copy
```
{
"name": "get_database_schema",
"description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
"parameters": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "what data should be retrived"
}
},
"required": [
"question"
]
},
"webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
```
##### Response
201400403
application/json Copy Function is created
```
{
"function": {
"name": "get_database_schema",
"description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
"parameters": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "what data should be retrived"
}
},
"required": [
"question"
]
},
"webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Function name |
| `description`required | `string` | Function description |
| `parameters`required | `object` | Function arguments |
| `webhook_url`required | `string` | Url for function invocation |
##### Response `201``application/json`
1 fields
Function is created
| Field | Type | Description |
| --- | --- | --- |
| `function` | `object` | Function configuration |
| `name`required | `string` | Function name |
| `description`required | `string` | Function description |
| `parameters`required | `object` | Function arguments |
| `webhook_url`required | `string` | Url for function invocation |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`POST` `/system_prompt`
#### Set System Prompt
`setSystemPrompt`
Set a system prompt for a ChatBot.
##### Request
application/json Copy
```
{
"system_prompt": "You are ChatBot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```
##### Response
200400403
application/json Copy System prompt is created
```
{
"system_prompt": "You are ChatBot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | System prompt content |
##### Response `200``application/json`
1 fields
System prompt is created
| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | System prompt content |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`POST` `/temperature`
#### Set Temperature
`setTemperature`
Set a GPT temperature for a chatbot. The temperature controls the randomness of the text generated by GPT model. Lower temperatures make the model more deterministic and repetitive, while higher temperatures make the model more varied. You can learn more about temperature in the GPT documentation.
##### Request
application/json Copy
```
{
"temperature": 0.55
}
```
##### Response
200400403
application/json Copy System prompt is created
```
{
"temperature": 0.55
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | GPT Temperature. |
##### Response `200``application/json`
1 fields
System prompt is created
| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | GPT Temperature. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/functions`
#### List Functions
`listFunction`
Provides a list of registered functions.
##### Response
200400403
application/json Copy Functions
```
{
"functions": [
{
"name": "get_database_schema",
"description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
"parameters": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "what data should be retrived"
}
},
"required": [
"question"
]
},
"webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
]
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
##### Response `200``application/json`
1 fields
Functions
| Field | Type | Description |
| --- | --- | --- |
| `functions` | `array` | Functions |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/system_prompt`
#### Get System Prompt
`getSystemPrompt`
Get a configured system prompt for a ChatBot.
##### Response
200400403404
application/json Copy System prompt
```
{
"system_prompt": "You are chatbot called ChatMTG by US Mortgage data company called staircase. You should help users with his question about the data. NEVER mention any table or column name."
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Response `200``application/json`
1 fields
System prompt
| Field | Type | Description |
| --- | --- | --- |
| `system_prompt`required | `string` | System prompt content |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/temperature`
#### Get Temperature
`getTemperature`
Get a configured GPT temperature for a ChatBot.
##### Response
200400403404
application/json Copy Temperature
```
{
"temperature": 0.55
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Response `200``application/json`
1 fields
Temperature
| Field | Type | Description |
| --- | --- | --- |
| `temperature`required | `number` | GPT Temperature. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/functions/{name}`
#### Get Function
`getFunction`
Provides a configuration of the registered function.
##### Response
200400403404
application/json Copy Function
```
{
"function": {
"name": "get_database_schema",
"description": "Use this function to get database schema of AWS Athena with columns and descriptions based what data should be retrived. You should ALWAYS use unfolded descriptions.",
"parameters": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "what data should be retrived"
}
},
"required": [
"question"
]
},
"webhook_url": "https://webhook.site/8efe8cf4-b7b5-4864-8b89-0302bf9749eb"
}
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `get_database_schema` | Function name |
##### Response `200``application/json`
1 fields
Function
| Field | Type | Description |
| --- | --- | --- |
| `function` | `object` | Function configuration |
| `name`required | `string` | Function name |
| `description`required | `string` | Function description |
| `parameters`required | `object` | Function arguments |
| `webhook_url`required | `string` | Url for function invocation |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`DELETE` `/functions/{name}`
#### Delete Function
`deleteFunction`
Delete a registered function.
##### Response
400403404
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `get_database_schema` | Function name |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`204`
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Conversation runtime
# Conversation runtime
Platform
Serves the conversation itself: holds the task set, runs the agent whose turn it is, calls the functions an answer triggers, and writes what was said to the loan record.
- **Used when**
— Behind every conversation above. Nothing in the fleet runs without it.
- **Collects**
- The message, the conversation it belongs to, and the task it advances.
- **Returns**
- The next message, the task state, and the record write the answer produced.
- **Hands off**
- Conversation management — the queue, the configuration and the work-tracking integration
- **Evidence**
- `chatbot`
- `chats`
- `chat-configuration-template`
## Operations
### Assistants
`POST` `/assistants`
#### Create a new assistant
`createAssistant`
Chat
This endpoint allows for the creation of a versatile assistant capable of interacting with different platforms such as OpenAI and Google. It enables the configuration of staircase service calls (functions). Users can define attributes like the assistant's name, functionality, and the tools it will use, ensuring the assistant is tailored to specific operational needs.
##### Request
Example1Example2
application/json Copy
```
{
"name": "General Helper",
"description": "An assistant designed to offer general help across various tasks, including scheduling, reminders, and basic inquiries.",
"platforms": [
{
"platform_name": "OpenAI",
"model": "gpt-4-1106-preview"
}
],
"tools": [
{
"tool_type": "retrival"
},
{
"tool_type": "code_interpretor"
},
{
"tool_type": "function",
"function": {
"http_method": "GET",
"path": "/data/retrieve",
"name": "retrieveData",
"description": "Function to retrieve data from the database.",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The identifier of the data to retrieve."
},
"fields": {
"type": "array",
"description": "The fields to retrieve.",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer",
"description": "The maximum number of records to retrieve."
},
"offset": {
"type": "integer",
"description": "The number of records to skip."
},
"order_by": {
"type": "string",
"description": "The field to order by."
},
"order_direction": {
"type": "string",
"description": "The direction to order by."
},
"filter": {
"type": "object",
"description": "The filter to apply."
},
"search": {
"type": "string",
"description": "The search to apply."
}
}
}
}
}
]
}
```
application/json Copy
```
{
"name": "EduBot",
"description": "An educational assistant designed to help students with learning, offering explanations, and quizzing capabilities.",
"platforms": [
{
"platform_name": "OpenAI",
"model": "gpt-4-1106-preview"
}
],
"tools": [
{
"tool_type": "function",
"function": {
"http_method": "POST",
"path": "/education/evaluate",
"name": "evaluateAnswer",
"description": "Function to evaluate student responses in quizzes.",
"parameters": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The question to evaluate."
},
"answer": {
"type": "string",
"description": "The answer to evaluate."
},
"options": {
"type": "array",
"description": "The options to evaluate.",
"items": {
"type": "string"
}
},
"correct_answer": {
"type": "string",
"description": "The correct answer."
},
"correct_options": {
"type": "array",
"description": "The correct options.",
"items": {
"type": "string"
}
},
"incorrect_answer": {
"type": "string",
"description": "The incorrect answer."
},
"incorrect_options": {
"type": "array",
"description": "The incorrect options.",
"items": {
"type": "string"
}
},
"explanation": {
"type": "string",
"description": "The explanation."
},
"metadata": {
"type": "object",
"description": "The metadata."
}
}
}
}
}
]
}
```
##### Request body`application/json`
10 fields
| Field | Type | Description |
| --- | --- | --- |
| `assistant_id` | `string` | Unique identifier for the assistant |
| `created_at` | `integer (int64)` | Timestamp of creation |
| `name` | `string` | Name of the assistant |
| `description` | `string` | Description of the assistant's purpose |
| `instructions` | `string` | Instructions for using the assistant |
| `platforms` | `array` | List of platforms the assistant is available on |
| `tools` | `array` | Tools utilized by the assistant |
| `file_ids` | `string[]` | List of OpenAI file identifiers associated with the assistant |
| `blob_file_ids` | `string[]` | List of `Persistence Blob` identifiers associated with the assistant |
| `metadata` | `object` | Metadata related to the assistant |
##### Response `201``application/json`
10 fields
Assistant created
| Field | Type | Description |
| --- | --- | --- |
| `assistant_id` | `string` | Unique identifier for the assistant |
| `created_at` | `integer (int64)` | Timestamp of creation |
| `name` | `string` | Name of the assistant |
| `description` | `string` | Description of the assistant's purpose |
| `instructions` | `string` | Instructions for using the assistant |
| `platforms` | `array` | List of platforms the assistant is available on |
| `tools` | `array` | Tools utilized by the assistant |
| `file_ids` | `string[]` | List of OpenAI file identifiers associated with the assistant |
| `blob_file_ids` | `string[]` | List of `Persistence Blob` identifiers associated with the assistant |
| `metadata` | `object` | Metadata related to the assistant |
##### Other responses
`400``403`
`GET` `/assistants`
#### List all assistants
`listAssistants`
Retrieves a list of all created assistants. This endpoint is useful for obtaining an overview of all assistants available in the system.
##### Response `200``application/json`
10 fields
A list of assistants
| Field | Type | Description |
| --- | --- | --- |
| `assistant_id` | `string` | Unique identifier for the assistant |
| `created_at` | `integer (int64)` | Timestamp of creation |
| `name` | `string` | Name of the assistant |
| `description` | `string` | Description of the assistant's purpose |
| `instructions` | `string` | Instructions for using the assistant |
| `platforms` | `array` | List of platforms the assistant is available on |
| `tools` | `array` | Tools utilized by the assistant |
| `file_ids` | `string[]` | List of OpenAI file identifiers associated with the assistant |
| `blob_file_ids` | `string[]` | List of `Persistence Blob` identifiers associated with the assistant |
| `metadata` | `object` | Metadata related to the assistant |
##### Other responses
`403``404`
### Chats
`POST` `/apps`
#### Create chat app
`createApp`
Create Chat App
Create new chat App. All incoming messages will be forwared as POST request to the provided webhook URL with app id, chat id and message submitted by user on UI. Service expects webhook to respond with 200 OK status code. JSON Schema of the request body:
```
{
"type": "object",
"properties": {
"app_id": {
"type": "string"
},
"chat_id": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"app_id",
"chat_id",
"message"
]
}
```
Example of the request body:
```
{
"app_id": "app_id",
"chat_id": "chat_id",
"message": "message"
}
```
##### Request
application/json Copy
```
{
"webhook_url": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
"app_name": "My App"
}
```
##### Response
201400
application/json Copy App created
```
{
"id": "01H9QPFE3CVK771YYD3MN9T4GQ",
"webhook_url": "https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a",
"app_name": "My App"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `webhook_url`required | `string` | Webhook URLExample `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a` |
| `app_name`required | `string` | App nameExample `My App` |
##### Response `201``application/json`
3 fields
App created
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | App IDExample `01H9QPFE3CVK771YYD3MN9T4GQ` |
| `webhook_url` | `string` | Webhook URLExample `https://webhook.site/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a` |
| `app_name` | `string` | App nameExample `My App` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/apps/{app_id}/chats/{chat_id}/messages`
#### Send message
`sendMessage`
Send message to chat.
##### Request
application/json Copy
```
{
"message": "Hello World"
}
```
##### Response
200400404
application/json Copy Message sent
```
{
"message": "Message sent successfully"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `app_id` required | `string` path | `01H9QPFE3CVK771YYD3MN9T4GQ` | App ID |
| `chat_id` required | `string` path | `01H9QQ1AB6HQSB8DEESRW3Z0Z8` | Chat ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | MessageExample `Hello World` |
##### Response `200``application/json`
1 fields
Message sent
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response messageExample `Message sent successfully` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Runs
`POST` `/runs`
#### Create add message and run
`createMessageAndRun`
Submits a message and initiates a run process based on that message. This is typically used to trigger processing of a user's input by the assistant.
##### Request
example1example2
application/json Copy
```
{
"thread_id": "thread_321",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Can you also provide tomorrow's forecast?"
}
}
],
"assistant_id": "assistant_654"
}
```
application/json Copy
```
{
"thread_id": "thread_321",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "I need assistance with organizing a team event."
}
}
],
"orchestrator_assistant_id": "assistant_9012"
}
```
##### Request body`application/json`
11 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | The identifier, which can be referenced in API endpoints. |
| `message_id` | `string` | The identifier, which can be referenced in API endpoints. |
| `created_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the message was created. |
| `thread_id`required | `string` | The identifier of the thread that the message belongs to. |
| `role`required | `string` | The role of the message.`user` |
| `content`required | `string` | The content of the message. |
| `file_ids` | `string[]` | The file IDs associated with the message. |
| `assistant_id` | `string` | The identifier of the assistant that should process the message. |
| `orchestrator_assistant_id` | `string` | The identifier of the assistant that should orchestrate the message. |
| `run_id` | `string` | The identifier of the run that processed the message. |
| `metadata` | `object` | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. |
##### Response `201``application/json`
13 fields
Message added and run initiated
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | The identifier, which can be referenced in API endpoints. |
| `created_at`required | `integer (int64)` | The Unix timestamp (in seconds) for when the run was created. |
| `assistant_id`required | `string` | The identifier of the assistant that should process the message. |
| `thread_id`required | `string` | The identifier of the thread that the message belongs to. |
| `status`required | `string` | The status of the run.`completed``in_progress` |
| `started_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run was started. |
| `expires_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run will expire. |
| `cancelled_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run was cancelled. |
| `failed_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run failed. |
| `completed_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run completed. |
| `last_error` | `string` | The last error that occurred during the run. |
| `platforms` | `array` | The platforms that the run was processed on. |
| `metadata` | `object` | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. |
##### Other responses
`403`
`GET` `/runs/{run_id}`
#### Get a run by ID
`getRun`
Retrieves the details of a specific run by its unique identifier.
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `run_id` required | `string` path | `123` | Unique identifier of the run |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
##### Response `200``application/json`
13 fields
Run details
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | The identifier, which can be referenced in API endpoints. |
| `created_at`required | `integer (int64)` | The Unix timestamp (in seconds) for when the run was created. |
| `assistant_id`required | `string` | The identifier of the assistant that should process the message. |
| `thread_id`required | `string` | The identifier of the thread that the message belongs to. |
| `status`required | `string` | The status of the run.`completed``in_progress` |
| `started_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run was started. |
| `expires_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run will expire. |
| `cancelled_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run was cancelled. |
| `failed_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run failed. |
| `completed_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the run completed. |
| `last_error` | `string` | The last error that occurred during the run. |
| `platforms` | `array` | The platforms that the run was processed on. |
| `metadata` | `object` | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. |
##### Other responses
`403``404`
### Threads
`POST` `/threads`
#### Create a new thread
`createThread`
This endpoint allows for the creation of a new thread. Threads are used to group messages together, allowing for the tracking of conversations between users and assistants.
##### Request
application/json Copy
```
{
"transaction_id": "12345"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | The transaction ID associated with the thread |
##### Response `201``application/json`
3 fields
Thread created
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The identifier, which can be referenced in API endpoints. |
| `created_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the thread was created. |
| `metadata` | `object` | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. |
##### Other responses
`400``403`
`GET` `/threads`
#### Fetches chat threads associated with a given transaction ID.
`retrieveChatThreads`
Retrieve Chat Threads by Transaction ID
Fetches chat threads associated with a given transaction ID.
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` query | — | The transaction ID to fetch chat threads for. |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
##### Response `200``application/json`
1 fields
A list of chat threads.
| Field | Type | Description |
| --- | --- | --- |
| `chat_threads` | `array` | A list of chat threads. |
##### Response `404``application/json`
1 fields
Chat thread not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Chat thread not found.Example `Chat thread not found` |
##### Other responses
`403`
### Messages
`GET` `/threads/{thread_id}/messages`
#### List all messages in a thread
`listMessages`
Retrieves a list of all messages in a specific thread. This endpoint is useful for obtaining an overview of all messages in a thread.
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `thread_id` required | `string` path | `123` | Unique identifier of the thread |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
##### Response `200``application/json`
11 fields
A list of messages
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | The identifier, which can be referenced in API endpoints. |
| `message_id` | `string` | The identifier, which can be referenced in API endpoints. |
| `created_at` | `integer (int64)` | The Unix timestamp (in seconds) for when the message was created. |
| `thread_id`required | `string` | The identifier of the thread that the message belongs to. |
| `role`required | `string` | The role of the message.`user` |
| `content`required | `string` | The content of the message. |
| `file_ids` | `string[]` | The file IDs associated with the message. |
| `assistant_id` | `string` | The identifier of the assistant that should process the message. |
| `orchestrator_assistant_id` | `string` | The identifier of the assistant that should orchestrate the message. |
| `run_id` | `string` | The identifier of the run that processed the message. |
| `metadata` | `object` | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. |
##### Other responses
`403``404`
### Credentials
`POST` `/credentials`
#### Create a new credential
`createCredential`
This endpoint allows for the creation of a new credential. Credentials are used to authenticate users and assistants, ensuring that only authorized users can access the system.
##### Request
application/json Copy
```
{
"partner": "12345",
"value": "12345"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `partner` | `string` | The partner associated with the credential`Google``OpenAI` |
| `value` | `string` | The value of the credential |
##### Response `201``application/json`
2 fields
Credential created
| Field | Type | Description |
| --- | --- | --- |
| `partner` | `string` | The partner associated with the credential |
| `value` | `string` | The value of the credential |
##### Other responses
`400``403`
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Correction
# Correction
Products
Reopens a subject the borrower has already answered so an answer can be changed without restarting the application.
- **Used when**
— Wherever a borrower or a reviewer finds an answer that is wrong, at any point before or after submission.
- **Collects**
- The corrected answer, and which subject it belongs to.
- **Returns**
- The updated record, and the downstream steps the change invalidated.
- **Evidence**
- `bot-correction`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Counterparty document expectations
# Counterparty document expectations
Data also Providers
Loads counterparty contact details and document requirements from spreadsheets into the graph store, mapping each requirement onto the governed vocabulary and setting aside anything that does not map.
- **Used when**
— When an expectations workbook arrives and its contents need to become queryable facts rather than a file.
- **Loads first**
- The upload skill, followed exactly.
- The schema-exploration skill, to confirm the current shape of every entity and relationship it will write.
- The persistence patterns, for validation, ingestion and read-back.
- **Returns**
- The source workbook, sheet, row count, counterparty count and contact count.
- The target environment and the verified account.
- The schema mappings used, and the validation and ingestion status.
- Records written, by type.
- The unresolved sidecar and its count.
- A read-back sample, and any schema gap that prevented a fact from being stored.
- **Hands off**
- Model curator — extending the schema when a fact has nowhere to go
## Others in Data
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Credit
# Credit
Products
Takes the borrower's consent to a credit enquiry, runs it, and brings the result back into the conversation so the liabilities it reports can be confirmed rather than typed.
- **Used when**
— After identity, and before liabilities — the enquiry is what fills the liability list the next conversation reviews.
- **Collects**
- Explicit consent to the enquiry, recorded as its own evidence.
- The result of the enquiry, held against the loan record.
- **Returns**
- The credit result, and a liability list for review rather than a blank form.
- **Hands off**
- Liabilities — reviewing and completing the reported liabilities
- **Evidence**
- `bot-credit-collector`
- `bot-credit-assistant`
- `consent-bot`
- `liabilities-bot-api_calls`
- `credit-report-tasksets`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Data-lake assistant
# Data-lake assistant
Data
Answers questions over the accumulated loan and partner data in plain language, and draws the chart where a chart is the answer.
- **Used when**
— When someone needs a figure out of the warehouse and does not want to write the query.
- **Collects**
- The question, and which body of data it should be answered from.
- **Returns**
- The answer, the query behind it, and a chart where one was asked for.
- **Evidence**
- `prompt-graphql-data`
## Operations
### ChatMTG
`POST` `/handle_query`
#### Handle US Data ChatMTG querying via SQL query
`handleUSDataQueryingViaSQL`
Endpoint function serves as an interface for users to interact with a US Data database by accepting a SQL query as an input and executing the query.
##### Request
application/json Copy
```
{
"sql": "select count(*) from \"sc-us-data-consumer-data\""
}
```
##### Response
200400403
application/json Copy Success
```
Total Number of People - 258,617,916
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `sql`required | `string` | SQL statement |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
## Others in Data
- Counterparty document expectations
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Dataset fulfilment
# Dataset fulfilment
Data
Turns an approved data request into a scoped extract — resolving which organisation it belongs to, mapping the requested field names onto the canonical model, and returning either the result directly or a time-limited download link.
- **Used when**
— When someone with authority to ask needs data out of the graph store and the request arrives as a sentence rather than as a query.
- **Loads first**
- The persistence product's own access patterns, before any read.
- Its access bootstrap, which establishes the environment and the verified credential source.
- **Returns**
- How it was invoked, how it read the request, and the organisation scope it resolved.
- The environment, verified credential source and discovered configuration, with no secret values.
- What validation found — a missing scope, an unverified requester, an unmapped field.
- The extraction plan: requested field names, the canonical fields they map to, and anything unmapped.
- The action taken, the workflow status, and the artifact metadata the workflow returned.
- The exact missing input, when it is blocked.
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Declarations
# Declarations
Products
Collects the declaration questions the application requires, and the follow-up detail wherever an answer needs one.
- **Used when**
— Near the end of the task set, and again whenever a later step raises a question the borrower has to answer in writing.
- **Collects**
- Each declaration, with the follow-up detail an affirmative answer needs.
- An explicit skip, where the flow permits one, recorded as a skip rather than as a blank.
- **Returns**
- The declaration answers on the record, with any detail attached to the answer that needed it.
- **Evidence**
- `bot-additional-information`
- `bot-additional-information-skip`
- `chatbot-requests`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Demographic details
# Demographic details
Products
Collects the regulated demographic questions, including the borrower's right to decline each of them.
- **Used when**
— In the forms stage, where the wording and the decline option are fixed by regulation rather than by the product.
- **Collects**
- Ethnicity, race and sex, each answerable more than once.
- A recorded decline, which is a valid answer rather than a missing one.
- How the information was provided — in person, by telephone, or by the borrower directly.
- **Returns**
- The demographic fields, with the collection method recorded beside them.
- **Evidence**
- `bot-demographic-details`
- `bot-demographic-details-collector`
- `bot-coborrower-demographic-details-collector`
- `start-loan-application-forms`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Design implementation
# Design implementation
Delivery
Translates a design into existing interface code, preserving the business logic underneath and locking in the breakpoints.
- **Used when**
— When a design has changed and the code has to match it without the behaviour moving.
- **Loads first**
- The design-to-code skill.
- The responsive-test skill, for the coverage the change needs.
- **Returns**
- A summary of the interface changes.
- The files updated and why.
- The result of checking recent commits for an override that would undo the change.
- Tests added or updated, with the lane chosen and the run results.
- **Hands off**
- Design testing — writing the tests that hold the change in place
- Interface triage — triaging a defect rather than implementing a design
## Others in Delivery
- Analytics instrumentation
- Application scaffolding
- Design testing
- Interface triage
- Marketplace architecture
- Sharing portals
---
# Design testing
# Design testing
Delivery
Writes the tests that verify an interface renders correctly across phone, tablet and desktop, in whichever of the two lanes fits — mocked specifications for the design itself, or real-device specifications for behaviour.
- **Used when**
— When a design-driven change needs coverage, or when an existing design test proved too weak to catch a regression.
- **Loads first**
- The responsive-test skill, and the design-to-code and bug-fix skills for the context of the change.
- **Returns**
- The lane decision and the reasoning behind it.
- The specifications created or updated.
- The breakpoint and device configuration used.
- The assertions added, and what each is for.
- The command and results, or a clear account of why the run could not happen.
- **Hands off**
- Design implementation — implementing the design change itself
- Interface triage — diagnosing and fixing the defect
## Others in Delivery
- Analytics instrumentation
- Application scaffolding
- Design implementation
- Interface triage
- Marketplace architecture
- Sharing portals
---
# Employment and income
# Employment and income
Products
Collects employment and the income that comes from it — employer, role, dates, and the pay in the components a lender underwrites: base, overtime, bonus and commission.
- **Used when**
— After the borrower is identified and reachable, and again for each previous employer needed to cover the required history.
- **Collects**
- The current employer, the role, the start date, and whether the borrower is still there.
- Pay, separated into base, overtime, bonus and commission.
- Previous employment, with dates, until the required history is covered.
- The same for a co-borrower.
- **Returns**
- The employment records and the income components on each, written to the loan record.
- **Hands off**
- Self-employment income — income from a business the borrower owns
- Other income — income from any source that is not employment
- **Evidence**
- `bot-employment-collector`
- `bot-employments-collector`
- `bot-previous-employment-collector`
- `bot-coborrower-employment-collector`
- `bot-coborrower-previous_employment-collector`
- `bots-employment-income-details`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# File sync
# File sync
Providers
Builds the scheduled workflow that copies a configured storage location into an external partner's file share: the infrastructure, a planning and cost gate, per-file workers, an aggregate, and the credential and configuration handling around them.
- **Used when**
— When files have to leave internal storage for a partner's share on a schedule, and the run has to be safe to repeat.
- **Loads first**
- The batch-workflow skill, for the distributed shape.
- The inbound-transfer skill, where the destination is a plain file-transfer endpoint, with the direction reversed.
- The continuous-integration skill, for the per-environment deployment path.
- **Returns**
- The chosen destination provider and its authentication flow, confirmed with the requester.
- The repository layout — infrastructure, handlers, provider adapters, tests.
- The parameter and secret schema, with the exact commands per environment.
- The runtime contract: the invocation event, the manifest, and the summary.
- The permissions actually granted, least-privilege.
- The deployment files added, and how the target environment is wired.
- A verification log covering a dry run, a single-file transfer, an idempotent rerun, a change-detection rerun and the schedule.
- The inputs still owed, and rollback notes for both code and configuration.
## Others in Providers
- Marketing stack
- Roster workflow
- Send lifecycle
---
# Frequently-asked questions
# Frequently-asked questions
Products
Answers a borrower's questions from a curated knowledge base rather than from the model's general knowledge, with the source behind each answer.
- **Used when**
— At any point in the conversation, alongside whichever subject is open.
- **Collects**
- The question, and the subject it was asked from.
- **Returns**
- The answer, and the document it came from.
- The question itself, recorded, so an unanswered one becomes a knowledge-base gap.
- **Evidence**
- `bot-faq-support`
- `chatbot-knowledge-update`
## Operations
### FAQ bot service
`GET` `/`
#### Get Bot Knowledge
`getKnowledge`
Get knowledge of faq bot
Get extra bot knowledge
##### Response
403500
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
`POST` `/`
#### Update Bot Knowledge
`updateBotKnowledge`
Update knowledge
Patch bot
##### Response
403500
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
`DELETE` `/{knowledge_id}`
#### Delete Bot Knowledge
`deleteKnowledge`
Delete extra knowledge
Delete extra bot knowdlege from faq-bot-service
##### Response
403500
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `knowledge_id` required | `string` path | `id_knowledge` | Knowledge id |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`204`
`POST` `/slab`
#### Update Bot Knowledge Slab
`updateBotKnowledgeSlab`
Update knowledge
Slab webhook for updating bot knowledge
##### Request
application/json Copy
```
{
"type": "post_update",
"post": {
"id": "elaykynn",
"title": "Neuromancer",
"link_access": "internal",
"state": "published",
"version": 1,
"bannerUrl": null
},
"old_post": {
"state": "archived",
"link_access": "internal",
"bannerUrl": null,
"ownerId": "l7ibj9w0",
"archiverId": "l7ibj9w0",
"publisherId": "l7ibj9w0",
"seriesId": null
},
"archiver": null,
"owner": {
"id": "l7ibj9w0",
"name": "William Gibson"
},
"publisher": {
"id": "l7ibj9w0",
"name": "William Gibson"
},
"series": null
}
```
##### Response
403500
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
`POST` `/sync`
#### Sync Bot Knowledge
`syncBotKnowledgeSlab`
Sync knowledge
Slab webhook for updating bot knowledge from Slab and knowledge database
##### Response
403500
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Gifts and grants
# Gifts and grants
Products
Collects funds given to the borrower rather than held by them — the donor, the relationship, the amount, and whether the funds have arrived.
- **Used when**
— Where the assets conversation found a deposit the borrower's own accounts do not cover.
- **Collects**
- The donor, their relationship to the borrower, and the amount.
- Whether the funds have been received, and where they sit.
- Whether the source is a gift or a grant programme.
- **Returns**
- One record per gift or grant, typed so the deposit calculation can treat it correctly.
- **Hands off**
- Assets — funds the borrower already holds
- **Evidence**
- `bot-gift-or-grant-assets-collector`
- `bot-gift-or-grants-interactive`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Interface triage
# Interface triage
Delivery
Triages and fixes interface defects: confirms the delta against the design reference, audits recent commits for the override that caused it, applies the smallest correcting change, and strengthens the tests so it cannot return.
- **Used when**
— When something renders wrongly and the cause is not yet known.
- **Loads first**
- The bug-fix skill and the responsive-test skill.
- The shared engineering guidelines.
- **Returns**
- The root cause, named as one of a design delta, an override, missing coverage or a logic regression.
- The files changed and why.
- The override or commit that caused the regression, with its identifier where one exists.
- The test coverage added, and which lane it went in.
- Test run results confirming both the fix and the absence of regressions.
## Others in Delivery
- Analytics instrumentation
- Application scaffolding
- Design implementation
- Design testing
- Marketplace architecture
- Sharing portals
---
# Knowledge search
# Knowledge search
Data
Builds reusable retrieval agents that answer from a curated document corpus — embeddings, a search index, a knowledge library, schema and header mapping, reuse of prior decisions, confidence thresholds and a human review loop.
- **Used when**
— When a question should be answered from a defined corpus rather than from a model's general knowledge, and the answer needs a confidence and a reviewer.
- **Loads first**
- The retrieval-system and agent-building skills.
- The shared engineering guidelines.
- **Returns**
- Whether the use case is retrieval at all, and why.
- The reusable agent boundary and its runtime contract.
- The corpus and metadata contract.
- The retrieval and confidence policy.
- The production stack and the local emulation path that replays it.
- The human review and learning loop for runtime decisions.
- The evaluation and operations plan, and an implementation checklist.
- **Hands off**
- Search to production — taking a retrieval system from prototype to production
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Liabilities
# Liabilities
Products
Reviews the debts the credit enquiry reported, corrects them, and collects the ones it did not — the obligations that do not appear on a credit file.
- **Used when**
— Directly after the credit enquiry, so the borrower confirms a list rather than recalling one.
- **Collects**
- Each reported debt, confirmed, corrected, or marked as belonging to someone else.
- Obligations no credit file carries, entered by the borrower.
- The verification state of each, so a disputed entry is visible as one.
- **Returns**
- The liability schedule on the loan record, with the source of each entry.
- **Hands off**
- Mortgage details — a mortgage secured on a property the borrower owns
- **Evidence**
- `bot-liabilities-collector`
- `bot-liabilities-interactive`
- `bot-liabilities-other-liabilities-collector`
- `bot-liabilities-verification`
- `bot-other-liabilities`
- `bot-other-liabilities-collector`
- `bot-other-liabilities-interactive`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Loan lookup
# Loan lookup
Products
Finds an existing application from what the borrower can remember, so a returning conversation resumes rather than restarts.
- **Used when**
— Whenever someone returns and the application they started is not obvious from their session.
- **Collects**
- Whatever identifies the application — an electronic-mail address, a reference, a property.
- **Returns**
- The matched application, and the task set resumed at the point it stopped.
- **Evidence**
- `bot-lookup`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Mail campaign operations
# Mail campaign operations
Platform
Operates the deployed mail-campaign workflow: validating the population for a run, launching it, watching it, and reconciling what came back against what was sent.
- **Used when**
— When a large physical-mail run needs launching or checking, or when the campaign workflow itself needs changing.
- **Loads first**
- The mail-campaign skill, for the launch, validation and monitoring workflow.
- The persistence patterns, before reviewing membership writes or reading results back.
- The batch-workflow and shared engineering guidance, before changing the workflow, its infrastructure, its alerting or its deployment path.
- **Returns**
- The target environment and account.
- The campaign identifier, name and purpose.
- The input location and the validated population count.
- The cost estimate and its approval status.
- The workflow execution identifier, the output prefix and the manifest written.
- Failure counts, and how to retry or resume.
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Marketing stack
# Marketing stack
Providers also Delivery
Orchestrates the whole measurement stack across consoles and code — tag management, analytics, search visibility, advertising linkage, the access each of those needs, and the handoff to whoever verifies it.
- **Used when**
— When measurement is being set up end to end rather than one piece at a time.
- **Loads first**
- The console-side order of operations, which it owns.
- **Returns**
- The sequence, in order, across every console and the code.
- For each access problem, who owns the permission in generic terms and a ready-to-send request naming the exact role.
- The identity question resolved: which account must own new properties, so ownership matches policy.
- The verification handoff.
- **Hands off**
- Analytics instrumentation — installing the tag in the application source
## Others in Providers
- File sync
- Roster workflow
- Send lifecycle
---
# Marketplace architecture
# Marketplace architecture
Delivery
Architects the multi-tenant platform through which products are packaged, distributed and installed — a central account governing per-customer accounts, a registry of components and releases, and the four ecosystem products underneath it: domain routing, account management, the product deployer and the tenant-side reconciler.
- **Used when**
— When a product needs to be distributed to many isolated tenants, or when one of the four ecosystem products is being built or changed.
- **Loads first**
- The marketplace skill and the skill for each ecosystem product.
- The shared engineering guidelines.
- **Returns**
- The tenancy model, with any deviation called out.
- The control-plane and data-plane boundary — what lives centrally, what lives in each tenant.
- The component artifact contract, its versioning scheme and its immutability rules.
- The registry design and its access patterns.
- The interface — its operations, their schemas, the authorisation model and the idempotency strategy.
- The cross-account deployment mechanism, with the rationale for the choice.
- The bootstrap plan and the fixed order the ecosystem products come up in.
- A verification plan that registers, releases, subscribes, rolls back and unsubscribes against a throwaway tenant.
## Others in Delivery
- Analytics instrumentation
- Application scaffolding
- Design implementation
- Design testing
- Interface triage
- Sharing portals
---
# Message assistant
# Message assistant
Platform
Answers questions about what has been sent to a consumer, and lets a non-technical user propose, revise, or retire a message template through a plain-language review conversation that captures the approved wording.
Outline
A description of this agent has not been written yet.
What would be here:
- When it runs, and what triggers it
- What it loads before it acts
- What it returns
- Which peer owns the adjacent work
Source: its own specification — this agent is deployed and the network document records what it does, but neither kit carries its contract
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Rule editor
- Short links
- Solver services
- Template inventory
---
# Metric reconciliation
# Metric reconciliation
Data
Reconciles the same metric across vendors and sources so the figures compare like with like, and records why they differed.
- **Used when**
— When two systems report the same measure differently, and the definition, the freshness, the window or the field mapping may be the reason.
- **Loads first**
- The metric-unification skill.
- The atomic-data skill, for the normalised shape the comparison runs on.
- **Returns**
- The coverage status against the governed vocabulary.
- The mappings and the normalisation decisions taken.
- The assumptions made and the risks they carry.
- The findings, and recommendations in priority order.
- **Hands off**
- Question answering — answering a counting question and turning it into a shareable report
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Military service
# Military service
Products
Collects service history, which decides eligibility for the loan programmes that depend on it.
- **Used when**
— In the forms stage of the task set, alongside the other regulated questions.
- **Collects**
- Whether the borrower has served, in what capacity, and over what period.
- Surviving-spouse status, where it applies.
- The same for a co-borrower.
- **Returns**
- The service fields on the record, in the form the eligibility engines read.
- **Evidence**
- `bot-military`
- `bot-military-service-collector`
- `bot-coborrower-military-service-collector`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Model curator
# Model curator
Data
Guards the shared graph schema, so that every entity type, relationship, property, index, enumeration and required field passes one review and ingestion and query behaviour stay consistent across services.
- **Used when**
— When a schema change is being designed, reviewed or applied — a new entity type, a new relationship, a property, an index, an enumeration value, or a deprecation.
- **Loads first**
- The schema-exploration skill, and the current schema file, downloaded before anything is proposed.
- The update skill, for the workflow, the modelling principles and the review checklist.
- The persistence product's patterns, to confirm the resulting payloads and queries still comply.
- **Returns**
- A domain summary of the entities and relationships being changed.
- The explicit decision for each — a new entity, a new relationship, a new property, a derived index, or a deprecation.
- Required-field and enumeration changes, justified from real source data.
- Index additions, with their canonical source facts, change triggers and queries.
- The immutability and revision-modelling decisions.
- The exact schema difference applied, with validation and test results.
- Downstream impact on ingestion and queries.
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Mortgage details
# Mortgage details
Products
Collects the terms of the loan being applied for and of any mortgage already secured on a property the borrower owns — amount, purpose, occupancy and term.
- **Used when**
— After the collateral and the existing property are known.
- **Collects**
- The loan amount, its purpose, the intended occupancy and the term.
- Existing mortgages, with their balances, payments and liens.
- **Returns**
- The loan terms on the record, complete enough for a price to be run against them.
- **Hands off**
- Pricing — running a price against the collected terms
- **Evidence**
- `bot-mortgage-details-collector`
- `bot-mortgage-details-filter`
- `bot-mortgage-details-interactive`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Operations agent builder
# Operations agent builder
Creating new agents
Builds the operations agents that drive document and media pipelines: resolving the target environment from what the requester said or from their profile, discovering the deployed stack, starting and watching runs, handling replays and approval gates, and preparing configuration changes as reviewable proposals.
- **Used when**
— When a pipeline needs a conversational operator rather than a runbook, and the operator has to be safe against acting on the wrong environment.
- **Loads first**
- The agent-building skill, for the shared runtime pattern.
- The pipeline's own replay and staging-configuration playbooks.
- The change-history skill, so a configuration proposal is grounded in what changed before.
- **Returns**
- The agent architecture and its runtime boundary.
- The environment and stack discovery plan, naming the fields discovery must return.
- The request contract, separating fields resolved deterministically from fields the model owns, with environment gating.
- The tool inventory, grouped by the system each group touches.
- The clarification, approval, replay and proposal rules.
- A verification checklist against real operational behaviour.
- **Hands off**
- Assistant builder — the general task-triggered agent shape
## Others in Creating new agents
- Assistant builder
- Audit analyser
- Spend approval
---
# Other income
# Other income
Products
Collects income from every source that is neither employment nor a business the borrower owns — rental income, benefits, pensions, investments, support payments.
- **Used when**
— After employment and self-employment, and wherever the borrower states an amount those two conversations do not account for.
- **Collects**
- Each income source, its kind, its amount and its frequency.
- Rental income, with the property it comes from.
- The same for a co-borrower.
- **Returns**
- One record per income source, typed so underwriting can decide which of them qualify.
- **Evidence**
- `bot-additional-income-collector`
- `bot-additional-income-inquiry`
- `bot-additional-incomes-collector`
- `bot-other-income-details`
- `bot-coborrower-additional-income-collector`
- `bot-rental-income-assistant`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Personal identity
# Personal identity
Products
Opens the application and collects who the borrower is — legal name, date of birth, taxpayer identifier, citizenship and marital status.
- **Used when**
— First in the loan-application task set. Completing it is what turns an anonymous application into a named one.
- **Collects**
- Legal name, date of birth and taxpayer identifier.
- Citizenship status and marital status.
- The same set again for a co-borrower, through its own variant.
- **Returns**
- The identity fields written to the loan record, and the application named for the borrower.
- **Hands off**
- Credit — consent to pull credit, and the pull itself
- **Evidence**
- `bot-personal-identity`
- `bot-personal-identity-interactive`
- `bot-personal-identity-collector-old-`
- `bot-coborrower-personal-identity-collector`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Pipeline control panel
# Pipeline control panel
Data
Runs the document-processing pipeline on request: resolves which documents actually exist for a set of records, checks what has already been processed, dispatches only the remainder, replays failures, and confirms the results reached their destination.
- **Used when**
— When a batch of records needs its documents processed, when a previous run left failures behind, or when someone needs to know whether a given account's documents made it through.
- **Loads first**
- Its own dispatch workflow, followed step by step rather than improvised.
- The integration guide for the source system holding the document rows.
- The read patterns for the store that records what has already been processed.
- **Returns**
- The source environment, the processing target, and the run identifier.
- Input row counts, unique record counts, and how many fall outside supported handling.
- Document-metadata counts, storage verification counts, and any location that could not be read.
- The already-processed count and the count remaining to dispatch.
- Dry-run and live dispatch counts, the queues targeted, and the manifest written.
- Verification of the processed results, and a summary of any follow-up requests raised.
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Preapproval letter
# Preapproval letter
Products
Produces the preapproval letter from the priced application, and refreshes it when the price behind it moves.
- **Used when**
— After a price is selected, and again whenever the borrower needs a current letter.
- **Collects**
- Which property or amount the letter should be written for.
- **Returns**
- The letter, and the record of the price it was written against.
- **Evidence**
- `broker-bot`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Pricing
# Pricing
Products
Runs an actual price against the collected loan terms and explains the result in the conversation.
- **Used when**
— Once the loan terms, the credit result and the income are on the record.
- **Collects**
- Which of the priced options the borrower is choosing.
- **Returns**
- The priced options, and the selected one written to the loan record.
- **Hands off**
- Correction — changing a term the price was run against
- **Evidence**
- `bot-pricing`
- `bot-price-assistant`
- `bot-market-index`
- `price-bot-api_calls`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Property data exploration
# Property data exploration
Data
Answers questions about public property and business data in plain language — appraisal and parcel records, permits, registered companies, contractor reputation, geographic filters and the schema behind them — by driving the published tool surface rather than writing queries by hand.
- **Used when**
— When someone wants to count, list or cross-reference properties and businesses in a jurisdiction, or to understand what a schema field means.
- **Loads first**
- The tool-surface usage skill.
- The coverage record for the jurisdiction in question, so an answer can be qualified by what is actually held.
- **Returns**
- The question as it was understood, the jurisdiction, and the filters applied, including any default threshold it chose.
- The tools called in order, with their key parameters.
- The answer — counts, listings with their evidence, or schema excerpts.
- The method and the coverage limits, stated as how much of the population was inspected.
- Gaps, assumptions and blockers, each with the exact fix.
- **Hands off**
- Public record ingestion — ingesting, refreshing and indexing a jurisdiction's public records
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Public record ingestion
- Question answering
- Report catalog
- Search to production
---
# Public record ingestion
# Public record ingestion
Data
Brings a jurisdiction's public data online: discovers the sources, collects and validates them, loads and reconciles them into the query store, then publishes the jurisdiction's query table and coverage record and wires both into the tool surface.
- **Used when**
— When a new jurisdiction is being onboarded, an existing one refreshed, or an ingestion run monitored.
- **Loads first**
- The onboarding skill and the per-stage skills it drives.
- **Returns**
- The jurisdiction and sources targeted, and whether this is a pilot or the full set.
- Which skills were driven, and the per-stage outcome — artifact counts per source against row counts in the store.
- Completeness and freshness validation, with every gap named rather than implied.
- The indexing outcome: the validation gate result, the published table and coverage pointers, the tool wiring, per-source coverage gaps, and a smoke query proving the jurisdiction is served.
- Blockers, with the exact fix.
- **Hands off**
- Property data exploration — querying the jurisdiction once it is loaded and indexed
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Question answering
- Report catalog
- Search to production
---
# Question answering
# Question answering
Data
Resolves which approved source actually holds a figure, queries it live, and turns the verified answer into a secure, shareable, refreshing report.
- **Used when**
— When someone asks how many, or wants a table, a chart or a dashboard built on current data.
- **Loads first**
- The usage skills for each approved source — the query contract for live activity tables, the schema-exploration skill, the persistence product, and the shared business logic.
- The report-publishing path, only after the numbers are verified.
- **Returns**
- The resolved source and the query actually run.
- The answer, with the coverage it is bounded by.
- A local preview built from verified data, then, on approval, the published report, its refresh schedule and its access configuration.
- **Hands off**
- Capability map — changing or provisioning a platform product rather than consuming one
- Report catalog — registering the finished report where it can be found
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Report catalog
- Search to production
---
# Rate estimate
# Rate estimate
Products
Gives a borrower an indicative rate from a short conversation, before any application exists.
- **Used when**
— At the top of the funnel, where someone wants a number before they will give a full application.
- **Collects**
- Enough of the loan shape to price it — amount, property value, purpose and occupancy.
- A credit range, self-reported rather than pulled.
- **Returns**
- The estimate, and the message that presents it to the borrower.
- **Hands off**
- Pricing — an actual price against the collected terms
- **Evidence**
- `bot-personalized-rate-estimate`
- `bot-personalized-rate-estimate-calculator`
- `bot-personalized-rate-estimate-collector`
- `bot-personalized-rate-estimate-result-message`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
---
# Real estate owned
# Real estate owned
Products
Collects the properties the borrower already owns — address, value, how it is used, and what it earns or costs.
- **Used when**
— Where residency or income established that the borrower holds property besides the one being financed.
- **Collects**
- Each property, its address, its estimated value and how it is occupied.
- Rental income and holding costs, where it is let.
- The agent representing the borrower, where one is involved.
- **Returns**
- One record per property, joined to the income and the mortgage each carries.
- **Hands off**
- Mortgage details — the loan secured on a property the borrower owns
- **Evidence**
- `bot-real-estate-collector`
- `bot-real-estate-agent-interactive`
- `real-estate-interactive`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Residency
- Self-employment income
- Workspace assistant
---
# Report catalog
# Report catalog
Data
Builds and maintains the single page where existing reports are registered and found, with a command-line path for registering a new one.
- **Used when**
— When reports exist in several places and there is nowhere to look them up.
- **Loads first**
- Its own catalogue scaffold and deployment path.
- **Returns**
- The catalogue application and its deployment.
- The registration command and what a registered entry carries.
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Search to production
---
# Residency
# Residency
Products
Collects where the borrower lives now and where they lived before, with the dates, so the address history covers the required period without gaps.
- **Used when**
— Immediately after identity, and again wherever a gap in the address history has to be filled.
- **Collects**
- The current address, how long the borrower has been there, and whether they own or rent.
- Previous addresses, with dates, until the required history is covered.
- The same history for a co-borrower.
- **Returns**
- The address history written to the loan record, with the periods it covers.
- **Hands off**
- Real estate owned — properties the borrower owns
- **Evidence**
- `bot-residency`
- `bot-residency-collector`
- `bot-residency-interactive`
- `bot-previous-residency-collector`
- `bot-coborrower-residency-collector`
- `bot-coborrower-previous-residency-collector`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Self-employment income
- Workspace assistant
---
# Roster workflow
# Roster workflow
Providers
Takes each partner's uploaded client list, matches it against the records under management, and returns partner-branded settlement and authorisation paperwork the same day.
Outline
A description of this agent has not been written yet.
What would be here:
- When it runs, and what triggers it
- What it loads before it acts
- What it returns
- Which peer owns the adjacent work
Source: its own specification — this agent is deployed and the network document records what it does, but neither kit carries its contract
## Others in Providers
- File sync
- Marketing stack
- Send lifecycle
---
# Router
# Router
Routing
Reads the current roster and names which specialist and which skills fit the task, with the reasoning behind the choice.
- **Used when**
— At the start of any task where the right specialist is not obvious, or when someone wants an overview of what the fleet can do.
- **Loads first**
- The kit's own index, re-read on every request rather than recalled, so a newly added agent is routable the day it lands.
- The shared engineering guidelines, for the constraints every recommendation inherits.
- **Returns**
- The recommended agents and skills, with the rationale for each.
- How to invoke them.
---
# Rule editor
# Rule editor
Platform
Turns a plain-language request into a concrete change to phone-interaction rules, runs it against sample records to show exactly which numbers would and would not be called, and packages that before-and-after evidence for the rule owner to approve.
Outline
A description of this agent has not been written yet.
What would be here:
- When it runs, and what triggers it
- What it loads before it acts
- What it returns
- Which peer owns the adjacent work
Source: its own specification — this agent is deployed and the network document records what it does, but neither kit carries its contract
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Short links
- Solver services
- Template inventory
---
# Search to production
# Search to production
Data
Takes a retrieval system from a local prototype through to production: the index model, the migration off the local store, historical backfill, live ingestion per source, and the instructions an agent needs to use it.
- **Used when**
— When a retrieval prototype works and the question is what it takes to run it for real.
- **Loads first**
- The local prototype skill first, then the production retrieval skill.
- The batch-workflow skill, for the backfill.
- **Returns**
- The prototype's status, command surface and verification results.
- The corpus, chunk, link, embedding, metadata and data-governance contract.
- The readiness gate result and the questions still open.
- The production index model and the migration plan off the local store.
- The backfill design, with cost, idempotency, metrics and replay.
- The ingestion design per source.
- The rollout plan, the verification, and the remaining limitations.
- **Hands off**
- Knowledge search — designing the retrieval agent itself
## Others in Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
---
# Self-employment income
# Self-employment income
Products
Collects income from a business the borrower owns, including contract income reported on its own tax form.
- **Used when**
— Where the employment conversation established that the borrower is self-employed, or that some of their income is contract income.
- **Collects**
- The business, the borrower's ownership share, and how long it has traded.
- Income drawn from it, and the tax form it is reported on.
- **Returns**
- The self-employment income records on the loan record, separated from employed income.
- **Evidence**
- `bot-self-employment-details`
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Workspace assistant
---
# Send lifecycle
# Send lifecycle
Providers
Owns the whole dispatch and feedback loop as one lifecycle: provider setup, routing, the send handoff, delivery events, and ingestion of what comes back.
- **Used when**
— When a provider adapter, a send workflow, delivery-feedback processing or response ingestion is being built for a message channel.
- **Loads first**
- The communication-activity skill, for the lifecycle contract.
- The shared engineering guidelines.
- **Returns**
- The provider and routing configuration.
- The execution-artifact and send-payload schema.
- The provider-correlation and status-persistence plan.
- The event contract, where provider outcomes are consumed asynchronously.
- The criteria that close an activity's lifecycle.
- **Hands off**
- Audience selection — audience selection
- Template inventory — template management
- Channel assembly — runtime scoring
## Others in Providers
- File sync
- Marketing stack
- Roster workflow
---
# Sharing portals
# Sharing portals
Delivery also Providers
Builds secure external file-sharing portals: hosted sign-in, private folder browsing, per-user grants, administrator-managed accounts, a custom domain, runtime configuration and a design-matched interface.
- **Used when**
— When people outside the organisation need controlled access to files and a shared link is not an acceptable answer.
- **Loads first**
- The front-end and back-end skill, and the design-to-code skill.
- The responsive-test skill, and the continuous-integration skill.
- The shared engineering guidelines.
- **Returns**
- The architecture summary and the repository layout changes.
- The authentication and administrator-access design.
- The per-user file grant model.
- The interface implementation notes, and the files changed with the reason.
- Tests added or updated, with commands and results.
- The deployment path, the required configuration, and the promotion route between environments.
- A deployment runbook and rollback notes.
- A security verification checklist and any residual risk.
## Others in Delivery
- Analytics instrumentation
- Application scaffolding
- Design implementation
- Design testing
- Interface triage
- Marketplace architecture
---
# Short links
# Short links
Platform
Builds the link-shortening and click-telemetry service behind outbound messages: issuing short tokens, storing the link as a graph record, resolving a token through a graph query, redirecting, and publishing a click fact onto the shared event bus.
- **Used when**
— When outbound messages need trackable links and the click has to become a fact other systems can consume.
- **Loads first**
- The short-URL skill, for the issuance and resolution patterns.
- **Returns**
- The architecture: a private issuance interface, a public resolver, graph storage, graph-query resolution, event publication, and replay of the dead-letter queue.
- The data contract for the stored link and its optional schema-backed edges.
- The resolver's order of operations.
- The exact event contract for a published click.
- The dead-letter and replay behaviour.
- Infrastructure discovery and custom-domain routing decisions.
- The patterns explicitly forbidden, and why.
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Solver services
- Template inventory
---
# Solver services
# Solver services
Platform
Designs and scaffolds optimisation services: a distributed layer that prepares data at scale, a pure solver core, and the infrastructure that wires them together.
- **Used when**
— When assignment, scheduling or capacity has to be decided by an optimiser rather than by a sort.
- **Loads first**
- The solver-service skill, before any code is written.
- The shared engineering guidelines.
- **Returns**
- The optimisation model — decision variables, constraints, objective, and the input and output contracts.
- The service architecture.
- An implementation plan by layer.
- The verification strategy, covering both solver behaviour and an end-to-end run.
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Template inventory
---
# Spend approval
# Spend approval
Creating new agents
Builds the workflow that watches model spend against a threshold, opens an approval task when it is crossed, and raises the limit by a configured increment only after a human completes that task.
- **Used when**
— When a spend limit needs to move on evidence and approval rather than on someone noticing.
- **Loads first**
- The agent-building and batch-workflow skills.
- The continuous-integration skill, for the per-environment deployment path.
- **Returns**
- The repository layout — the workflow's task handlers, the approval webhook handler, shared configuration modules and tests.
- The state-machine shape, from plan through a per-user approval wait to the aggregate, and how the schedule starts it.
- The parameter and secret list, with the exact commands an operator runs per environment.
- The runtime contract: plan output, item schema, task body, webhook filter, ledger schema, and every named rejection reason.
- The permissions actually granted, least-privilege, per component.
- A verification log covering the approval path, a non-approver, a cap rejection, a drifted limit, a replayed webhook, a timeout, and a redrive.
- Rollback notes for both the code and the configuration.
## Others in Creating new agents
- Assistant builder
- Audit analyser
- Operations agent builder
---
# Template inventory
# Template inventory
Platform
Builds the systems that keep message templates versioned, reviewed and in step with whatever sends them — the repository layout, the metadata contract, discovery of the source tables, and one-time or recurring synchronisation from the operational store into a version-controlled inventory.
- **Used when**
— When templates live in an operational system and need to become reviewable artifacts, or when a template-management agent is being built.
- **Loads first**
- The channel-template skill, for the inventory and synchronisation patterns.
- The shared engineering guidelines.
- **Returns**
- The template repository layout and its metadata contract.
- The source-discovery result, or the minimal set of questions still unanswered.
- The create, read, update and delete workflow, and the synchronisation design.
- The active and inactive rules, and the family-to-variant rules.
- Acceptance checks for the inventory and for the runtime workflow.
- **Hands off**
- Audience selection — audience selection
- Send lifecycle — provider delivery
- Channel assembly — runtime scoring
## Others in Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
---
# Workspace assistant
# Workspace assistant
Products
The assistant inside the internal workspace: answers a reviewer's questions about an application in progress and drafts the message going back to the borrower.
- **Used when**
— While a person is working an application, rather than while a borrower is answering one.
- **Collects**
- The reviewer's question, and the application it is about.
- **Returns**
- The answer, and the draft reply for the reviewer to send or edit.
- **Evidence**
- `aira`
- `aira-messaging`
## Operations
### Workspaces
`POST` `/`
#### Create a new workspace
`createWorkspace`
##### Request
application/json Copy
```
{
"name": "Agent",
"default_assistant": {"assistant_name": "leadsGeneric", "context_message": "Questions related to leads."},
"assistants": [
{"assistant_name": "SendEmail", "context_message": "Questions related to sending emails."},
{"assistant_name": "GeneratePostcard", "context_message": "Questions related to generating postcards."}
]
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Name of the workspace |
| `default_assistant` | `object` | Assistant object |
| `assistant_name` | `string` | Name of the assistant |
| `context_message` | `string` | Context message for the assistant |
| `assistants`required | `array` | List of assistants for the workspace |
| `routing_model` | `string` | Routing model. Only GPT-4o and later models are supported. GPT4-4o mini is also supported. |
##### Response `200``application/json`
4 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Name of the workspace |
| `default_assistant` | `object` | Assistant object |
| `assistant_name` | `string` | Name of the assistant |
| `context_message` | `string` | Context message for the assistant |
| `assistants`required | `array` | List of assistants for the workspace |
| `routing_model` | `string` | Routing model. Only GPT-4o and later models are supported. GPT4-4o mini is also supported. |
`GET` `/{workspace_name}`
#### Get a workspace
`getWorkspace`
Get a workspace by name
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `workspace_name` required | `string` path | `my-workspace` | Name of the workspace |
##### Response `200``application/json`
4 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Name of the workspace |
| `default_assistant` | `object` | Assistant object |
| `assistant_name` | `string` | Name of the assistant |
| `context_message` | `string` | Context message for the assistant |
| `assistants`required | `array` | List of assistants for the workspace |
| `routing_model` | `string` | Routing model. Only GPT-4o and later models are supported. GPT4-4o mini is also supported. |
### AIRA Messaging
`POST` `/messaging/{workspace_name}/messages`
#### Send message
`sendMessage`
Send a message to the AIRA workspace
##### Request
application/json Copy
```
{
"connection_id": "123",
"x-sc-trace-id": "123",
"message": [
{
"type": "text",
"text": "Hello"
}
],
"payload": {
"person_identifier": "123",
"regenerate_response": true
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `workspace_name` required | `string` path | `workspace` | The name of the workspace |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `connection_id`required | `string` | The connection id |
| `x-sc-trace-id` | `string` | The trace id |
| `message`required | `object[]` | The message to send |
| `type`required | `string` | The type of the message`text` |
| `text`required | `string` | The content of the message |
| `payload`required | `object` | The payload |
| `person_identifier`required | `string` | The person identifier |
| `regenerate_response` | `boolean` | Regenerate the response |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error message |
##### Other responses
`200`
`GET` `/messaging/{connection_id}/messages`
#### List messages by connection ID
`listMessages`
List messages
List messages by connection id
##### Response
application/json Copy Messages history
```
{
"messages": [
{
"role": "user",
"content": "Hello"
},
{
"role": "assistant",
"content": "Hi"
}
],
"openai_thread_id": "123"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `connection_id` required | `string` path | `dfYn_eqooAMCFDA=` | The connection id |
##### Response `200``application/json`
2 fields
Messages history
| Field | Type | Description |
| --- | --- | --- |
| `messages` | `object[]` | The messages |
| `role` | `string` | The role`user``assistant` |
| `content` | `string` | The content |
| `openai_thread_id` | `string` | The openai thread id |
### Route
`POST` `/{workspace_name}/route`
#### Process route request
`processRouteRequest`
Process a route request
Process a route request for the specified workspace
##### Request
application/json Copy
```
{
"message_history": [{"role": "System", "content": ""}, {"role": "System", "content": ""}],
"input_text": ""
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `workspace_name` required | `string` path | `my-workspace` | Name of the workspace to route the request to |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `input_text` | `string` | Input text for the route |
| `message_history` | `object[]` | Message history |
| `role` | `string` | Role of the message`assistant``user` |
| `content` | `string` | Text of the message |
##### Response `200``application/json`
3 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `openai_assistant_id` | `string` | OpenAI assistant ID |
| `configuration_id` | `string` | Configuration ID |
| `assistant_name` | `string` | Staircase assistant name |
## Others in Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
---
# Routing
# Routing
The way into the fleet: one agent reads a request and hands it to the specialist that owns the work.
- Router
Reads the current roster and names which specialist and which skills fit the task, with the reasoning behind the choice.
---
# Runtimes
# Runtimes
The same registry served over a standard-input transport, a streaming HTTP transport, and an edge runtime.
Three transports, one tool registry. The standard-input entry is the path a desktop client launches; the HTTP entry is stateless, constructing a fresh server and transport per request, which is the shape a serverless deployment requires; the web handler bridges the same registry into an edge runtime.
Five separate agent clients have working install paths against the same surface.
- The same registry is served over a standard-input transport, a streaming HTTP transport, and an edge runtime.
- Documented, working install paths exist for five separate agent clients — this is a multi-client surface, not a single-vendor integration.
- Configuration is environment-supplied, so pointing the surface at a different set of jurisdictions is a configuration change rather than a release.
## How it works
Configuration is supplied by the environment, so pointing the surface at a different set of jurisdictions is a configuration change rather than a release.
The server holds no database. Query tools read published per-jurisdiction tables directly over HTTP by content address, range-reading the columns a query needs rather than downloading a dataset, which is why a consumer can run their own copy against the same published data instead of depending on a shared backend.
Every fetched range is hash-verified against its content address before it is returned, and a mismatch throws rather than being served.
---
# Skills
# Skills
Packaged, versioned know-how any agent or engineer picks up: how to integrate a partner, how to model data, how to test an interface.
A skill is a unit of instruction with a version, not prompt text pasted into an agent definition. An agent composes the skills a task needs, and a skill improved once improves every agent that composes it.
Writing knowledge down once and reusing it is what stops it evaporating when a person leaves or a system changes. The county onboarding runbook documented under bringing a jurisdiction online is a worked example: ten stages, each its own skill, run in sequence with an intake at the start and interruption only on a genuine blocker.
- Packaged, versioned know-how — how to integrate a partner, how to model data, how to test a design — that any agent or engineer picks up. Knowledge is written once and reused everywhere, so it compounds instead of evaporating when a person leaves or a system changes.
Packaged, versioned know-how — how to integrate a partner, how to model data, how to test a design — that any agent or engineer picks up. Knowledge is written once and reused everywhere, so it compounds instead of evaporating when a person leaves or a system changes.
---
# Tools
# Tools
The tool registry a client connects to: one definition set served over several transports, with a guarded query surface.
One registry is the single source both the standard-input entry and the HTTP entry read, so the two transports cannot drift apart. Every tool carries a title, a description, and a per-parameter description written for a model rather than for a reader who already knows the domain.
- One tool registry is the single source both transports read, so the stdio entry and the HTTP entry cannot drift apart.
- Every tool carries a title, a description, and a per-parameter description written for a model rather than for a reader who already knows the domain.
- Query tools are guarded in four layers: comment and literal stripping, multi-statement rejection, a read-only statement allowlist, and an unconditional row cap.
## How it works
The query tools accept caller-written SQL, which is only safe because the guard is explicit. Four layers, in order: comments and string literals are stripped before any keyword matching, so a value like `'copy'` inside a string cannot trip the filter; multiple statements are rejected; the statement must begin `SELECT` or `WITH`; and the caller's query is wrapped in an outer select with a row cap the caller cannot override.
Stripping literals before matching is what a plain keyword scan does not do. A scan over raw text rejects `owners_text ILIKE '%copy%'`, which is a legitimate query, and a guard that rejects legitimate queries is one callers route around.
Tools that author their own SQL use a separate path with positional binding and skip the caller validator, because they are safe by construction rather than by inspection.
## The registry
### `listClassesByDataGroup`
List classes by data group
List classes for a property data group with names and descriptions
- `groupName`stringrequired
The data group name, case-insensitive
### `listPropertiesByClassName`
List properties by class name
Lists JSON Schema property names for a property class (excludes source_http_request)
- `className`stringrequired
The class name, case-insensitive
### `getPropertySchema`
Get property schema by class and property
Returns the full JSON Schema object for a class property
- `className`stringrequired
Class name, case-insensitive
- `propertyName`stringrequired
Property name, case-insensitive
### `getVerifiedScriptExamples`
Get verified script examples
Get most relevant working examples of the code, that maps data to the canonical property schema
- `query`stringrequired
Description of the example meaning. Wll be used to search for similar examples.
- `topK`number
Number of results (default 5)
### `listOracleProperties`
List Oracle open-data properties
Paginated discovery of properties for a county. Returns slim entries (propertyId, parcelIdentifier, cid, county, fileSizeBytes) plus summary fields (address, marketValue, ownerName) when served from the query table. Use getOracleProperty to fetch full consolidated data for a specific entry.
- `county`string
Filter by county name (case-insensitive)
- `limit`number
Number of results to return (default 50, max 500)
- `offset`number
Zero-based offset for pagination (default 0)
### `getOracleProperty`
Get Oracle open-data property
Fetch the full consolidated property JSON (appraisal, permits, Sunbiz, BBB) from content-addressed storage. Provide exactly one of parcelIdentifier, propertyId, or cid.
- `parcelIdentifier`string
The property parcel identifier (digits) — looked up in the manifest to resolve its content-addressed storage content address
- `propertyId`string
The property UUID — looked up in the manifest to resolve its content-addressed storage content address
- `cid`string
content-addressed storage content address for the consolidated property JSON
- `county`string
County to look up the parcel/property in (case-insensitive). Selects which county's open data to read when the deployment serves multiple counties.
### `getOracleDatasetInfo`
Get Oracle open-data dataset info
Returns dataset-level metadata for a county: county, propertyCount (live row count when served from the query table), state, and provenance/content address fields on the legacy path. When per-source coverage is configured, also returns datasets[] with, per source (appraisal, permits, sunbiz, bbb), ingestedCount, expectedCount, completionPercent, and first/last loaded timestamps — so callers can qualify partial answers by coverage. For a coverage-only county (no property dataset served) propertyCount is null and propertyDatasetAvailable is false, so callers can distinguish a missing property table from a county with zero properties.
- `county`string
County to report dataset info for (case-insensitive). Selects which county's open data to read when the deployment serves multiple counties.
### `getPropertyPermits`
Get property permits (on-demand)
Fetch permit records for a property by parcel ID. Returns cached permits immediately if available. If not cached, enqueues a harvest job (reuses the permit-harvest Lambda) and returns a status indicating the harvest is in progress — poll again after ~90 seconds. Permits are cached to content-addressed storage after harvest completes.
- `parcelId`stringrequired
The property parcel identifier (digits, e.g. '1234567890000')
- `countyFips`string
County FIPS code (default: 12071 = Lee County FL)
### `findPropertiesInArea`
Find properties in an area
Returns the set of properties whose centroid (latitude/longitude) falls inside a user-supplied bounding box or polygon. Provide exactly one of bbox or polygon. Reads the per-county property query table (falls back to the derived geo index); no NOAA/FEMA geometry is used.
### `sumPropertyValueInArea`
Sum property value in an area
Returns the exact sum of avm_value over the properties whose centroid falls inside a user-supplied bounding box or polygon, plus the in-area count. Null valuations are treated as 0. Provide exactly one of bbox or polygon. Reads the per-county property query table (falls back to the derived geo index).
### `queryProperties`
Query properties (SQL)
Run a read-only SQL SELECT against a county's flat property query table (view name 'properties', one row per property) backed by embedded DuckDB. Use getPropertyQuerySchema first to see available columns. SAFETY: a single SELECT statement only (a leading WITH/CTE is allowed); multiple statements and any mutating or file/extension keyword (INSERT/UPDATE/DELETE/COPY/ATTACH/INSTALL/LOAD/PRAGMA/CALL/SET …) are rejected; results are always capped at 1000 rows.
- `county`stringrequired
County to query (case-insensitive), e.g. 'Lee'.
- `sql`stringrequired
A single read-only SELECT statement over the 'properties' view.
- `limit`number
Max rows to return (default 100, max 1000). Always enforced.
### `getPropertyQuerySchema`
Get property query schema
Returns the column list, DuckDB types, and a one-line description of each column of the 'properties' query table for a county, so queryProperties can be written without guessing. Notes that some coverage-dependent fields may be NULL.
- `county`stringrequired
County to describe (case-insensitive), e.g. 'Lee'.
### `queryPermits`
Query permits (SQL)
Run a read-only SQL SELECT against a county's flat permit query table (view name 'permits', one row per building permit) backed by embedded DuckDB. Use getPermitQuerySchema first to see available columns and getPermitCoverage to qualify aggregate answers by source. SAFETY: a single SELECT statement only (a leading WITH/CTE is allowed); multiple statements and any mutating or file/extension keyword (INSERT/UPDATE/DELETE/COPY/ATTACH/INSTALL/LOAD/PRAGMA/CALL/SET …) are rejected; results are always capped at 1000 rows.
- `county`stringrequired
County to query (case-insensitive), e.g. 'Lee'.
- `sql`stringrequired
A single read-only SELECT statement over the 'permits' view.
- `limit`number
Max rows to return (default 100, max 1000). Always enforced.
### `getPermitQuerySchema`
Get permit query schema
Returns the column list, DuckDB types, and a one-line description of each column of the 'permits' query table for a county, so queryPermits can be written without guessing. Notes that date/value fields are frequently NULL depending on the permit source.
- `county`stringrequired
County to describe (case-insensitive), e.g. 'Lee'.
### `getPermitCoverage`
Get permit coverage by source
Returns per-source-system permit coverage for a county from the 'permits' query table: each source_system with its permit_count and completion_date range (earliest/latest), plus the overall total. The donphan agent uses this to QUALIFY aggregate permit answers (permit data lags appraisals and some sources may have NULL dates).
- `county`stringrequired
County to report permit coverage for (case-insensitive), e.g. 'Lee'.
---
# The consumer application
# The consumer application
A borrower-facing application flow assembled from the mortgage products: conversational intake, verification calls, pricing, an automated decision, and a generated loan application with its standards export.
The flow is a queue of tasks with one task in progress at a time. Three task types cover everything in it: a conversational agent, a third-party API call, and a form. A fourth type groups tasks under a named milestone.
Each data domain is two agents rather than one. An inquiry agent gathers information conversationally and knows only which data points it needs; a schema agent takes the transcript and writes it into the canonical model. The inquiry agent never learns the storage shape, which is what keeps the conversation from being driven by the schema.
Task dependencies carry two separate gates: one deciding when a task may start, another deciding when its output may be committed. Separating them is what lets a background extraction run while a different agent is still talking to the borrower, without a write race.
## The flow
A borrower answers questions in conversation rather than filling a form. Each answer is written into the canonical model as it arrives, so the application is a live record from the first question rather than a form submitted at the end.
## The agents that conduct it
The application is not one agent. It is a set of them, each responsible for one section of the loan application — identity, residency, employment and income, assets, liabilities, real estate, declarations — with a router dispatching between them and each one writing into the same canonical record. A section is a separately versioned unit, so a change to how employment is collected does not touch how assets are.
Behavioural fixtures assert the exact tool calls each agent makes, and they run before a deploy. An agent that stops asking the right question fails the build rather than degrading quietly in front of a borrower.
How that is gated
## What it produces
- A completed loan application — the full standard form, populated from the conversation rather than transcribed from it.
- A standards export — the same record emitted in the industry interchange format, so any downstream system can read it without a bespoke mapping.
- A letter — the borrower-facing document, generated from the same record it was decided on.
## What it composes
- POS
- Identity
- Credit
- Employment
- Income
- Asset
- Price
- Government
- Approval
- Document
- Lexicon
---
# Data
# Data
Two domain models: the mortgage model covers the loan transaction end to end, and the property model covers the physical asset and the public record behind it.
Both models are class dictionaries: a class, its properties, each property's type, and the classes it points at. Every product request and response is a subset of one of them, so a field name on a product page resolves to a definition here rather than to a per-endpoint glossary.
The two are separate dictionaries with separate governance, and they overlap by name where both descend from the same standards work. The overlap below is computed from the two files rather than asserted.
## Mortgage model
The transaction: the parties, the loan and the mortgage plan behind it, the documents, the fees and taxes, income and employment, credit, insurance, the payment schedule and the borrower's wider financial profile. Definitions are complete sentences by rule.
The dictionary as written also models the platform that served it — its API objects, its ticketing, its tenancy and its own catalogue. Those classes are named and withheld rather than published, because a reader looking for the shape of a loan does not need the shape of the software that carried it.
- `address`
- `credit`
- `document`
- `employment`
- `employment_income`
- `fee`
- `finance_relation`
- `income`
- `insurance`
- `loan`
- `mortgage_application`
- `mortgage_plan`
- `payment`
- `person`
- `person_credit`
- `person_income`
- `pricing_schema`
- `property`
- `property_tax`
- `tax`
## Property model
The asset: parcel, structure, layout, lot, deed, tax, sales history, permits and the surrounding jurisdiction records. Grouped below by the question each class answers about a property, which is the grouping the extraction pipeline itself uses.
- `property_seed`
- `unnormalized_address`
- `address`
- `parcel`
- `person`
- `property`
- `tax`
- `tax_jurisdiction`
- `tax_exemption`
- `lot`
- `sales_history`
- `file`
- `layout`
- `flood_storm_information`
- `structure`
- `property_improvement`
- `utility`
- `deed`
- `geometry`
- `appliance`
- `homeowners_association`
- `hoa_policy`
- `loan`
- `property_ranking_overall`
- `inspection`
- `environment_characteristics`
- `safety_security`
- `transportation_access`
- `school`
- `tax_authority`
## Shared lineage
Both models descend from the same standards work, and the overlap is the evidence for that rather than a sentence claiming it. A row appears here because both dictionaries name the class; it disappears the moment either renames it.
A shared name is not a shared definition. The two models were governed separately and a class on both sides may carry different properties, so the table links to each side rather than merging them.
Shared classes are computed at build time by intersecting the class names in the two dictionaries: a class is listed because both models name it, and it drops out the moment either one renames it. A class with no property-model link exists in the property graph but is reached by no published data group, so it has no page.
| Class | Mortgage model | Property model |
| --- | --- | --- |
| `address` | open | open |
| `credit` | open | not published |
| `document` | open | not published |
| `employment` | open | not published |
| `fee` | open | not published |
| `finance relation` | open | not published |
| `income` | open | not published |
| `insurance` | open | not published |
| `loan` | open | open |
| `mortgage application` | open | not published |
| `mortgage plan` | open | not published |
| `payment` | open | not published |
| `person` | open | open |
| `pricing schema` | open | not published |
| `property` | open | open |
| `tax` | open | open |
---
# Mortgage model
# Mortgage model
The mortgage class dictionary: the loan transaction, its parties, its collateral and the documents and money that move with it.
The model derives from the industry standard for mortgage data and covers the whole life of a loan — origination, funding, secondary market and servicing — together with the document types the transaction produces.
The dictionary as written covers a second subject as well: the platform that served it, in classes for its API objects, its ticketing, its tenancy and its own product catalogue. Those are withheld by name, each with its reason, so what remains here is the mortgage.
It is a graph rather than a relational schema, and it is flat: no class nests another. A relationship between two classes is itself a class, whose properties join them. Every class is independently addressable and a relationship can carry its own attributes, which a foreign key cannot.
## How it is governed
Naming is a written law rather than a convention. Types, properties and relationships are lower snake case; abbreviations are spelled out unless expansion is painful; and the property suffix carries the type — an indicator is boolean, an identifier is an identifier, an amount and a percent are decimal, and a type is an enumeration whose range is a named enumeration set backed by its own file.
Definitions are required to be complete sentences that define the term rather than expand the acronym. The stated reason on record is future use by a conversational system: a definition reading as a glossary stub transfers nothing to a model reading it.
Every proposed change ran a fixed sequence: a use case submitted on a form, a draft class diagram, alignment against the existing model, review by a named domain expert, revision, notice to the requester, then publication.
## How it works
Identity is immutable. Every state of an entity is a new database-generated identifier, and a stable global identifier groups every state of the same real-world thing, named for its class. Reading history is a query over that group rather than an audit table, and a correction never destroys what it corrected.
An attribute becomes its own class on six tests: whether it repeats, whether it is shared, whether it has internal structure, whether it changes over time, whether it relates to other attributes, and how it is used. The tests are what kept the model from either flattening into wide records or exploding into a class per field.
There is a deprecation pipeline for the model itself: duplicate analysis, impact analysis across every consumer of a class, automatic upcasting of a caller's payload to the current model, and usage monitoring of classes on the way out. Several removals were executed through it, each with its own recorded runbook.
Validation is two-layered — see Lexicon for the serving surface. Syntactic shapes constrain datatype, enumeration, pattern, length and range. Semantic shapes carry conditional rules: if a borrower's marital status is married, the spouse's name becomes required.
## Classes
- `address`
- `credit`
- `document`
- `employment`
- `employment_income`
- `fee`
- `finance_relation`
- `income`
- `insurance`
- `loan`
- `mortgage_application`
- `mortgage_plan`
- `payment`
- `person`
- `person_credit`
- `person_income`
- `pricing_schema`
- `property`
- `property_tax`
- `tax`
## The classes carrying the most
| Class | Properties | Referenced by |
| --- | --- | --- |
| `address` | 36 | 0 |
| `insurance` | 32 | 1 |
| `loan` | 30 | 2 |
| `person` | 23 | 4 |
| `payment` | 16 | 1 |
| `pricing_schema` | 14 | 1 |
| `property` | 13 | 2 |
| `finance_relation` | 12 | 0 |
Derived from: mortgage class dictionary (repository source)
---
# address
# address
A physical location, described down to the components a postal system and a legal description each need.
An address describes a physical location described in terms of street address, city, state, region, province, country and other geo-location references.
## Why it matters
The widest class in the model, because an address has to satisfy several consumers at once: postal delivery, legal description, geocoding, and the jurisdiction lookups that tax and title depend on.
Components are separate properties rather than lines of text. A line is enough to print a letter and not enough to match two records, and matching is the operation that actually gets performed.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `address_format_type` | `string` | Address format type refers to the different conventions or standards used to structure and format addresses in various countries or regions. |
| `address_line_1` | `string` | Address line 1 is the first line of the address where the primary information for locating a specific location or recipient is provided. |
| `address_line_2` | `string` | Address line 2 is the second line of the address where the primary information for locating a specific location or recipient is provided. |
| `address_line_3` | `string` | Address line 3 is the third line of the address where the primary information for locating a specific location or recipient is provided. |
| `address_type` | `enumeration` | Address type is a classification or categorization of an address based on its purpose or characteristics. `as_shown_on_tax_return``corporate_headquarters``current``legal_entity_formation``mailing``other``primary``prior` |
| `address_type_other_description` | `string` | If an address type is 'other,' address type other description provides more details on the address type. |
| `address_unit_designator_type` | `enumeration` | Address unit designator type describes the category that a specific unit belongs to. `apartment``basement``building``condo``department``floor``front``hangar``key``lobby``lot``lower``office``penthouse``pier``rear``room``side``space``stop``suite``trailer``unit``upper` |
| `attention_to_name` | `string` | An attention to name on an address is an optional line that can be included in an address to indicate the name of a specific person or department within an organization to whom the mail is intended. |
| `carrier_route_code` | `string` | A carrier route code is a unique identifier assigned by the United States Postal Service (USPS) to a specific mail delivery route or group of addresses serviced by a single mail carrier. |
| `cbsa_code` | `string` | A CBSA code is a Canada Border Services Agency (CBSA) code, which is a unique identifier assigned to specific ports, airports, or border crossing points in Canada. The CBSA code helps facilitate the import/export process and customs clearance activities at these designated locations. |
| `city_name` | `string` | City name refers to the name of the city in which the address is located. |
| `country_code` | `string` | Country code is a code that represents the country in which the address is located. |
| `country_name` | `string` | Country name refers to the country where a person resides. |
| `county_code` | `string` | County code is a code that represents the county in which the address is located. |
| `county_name` | `string` | A property county name refers to the name of the county in which a property is located. In the United States, counties are geographic and political subdivisions of states, typically governed by a county government. Each county is identified by a unique name and is responsible for providing certain public services to residents, such as law enforcement, public schools, and infrastructure maintenance. |
| `created_datetime` | `dateTime` | Created_datetime describes when an address was created in a system. |
| `delivery_point_bar_code` | `dateTime` | A Delivery Point Barcode (DPBC) is a barcode used by the United States Postal Service (USPS) to facilitate the automated sorting and delivery of mail. It contains encoded information that helps identify the specific delivery point or address to which mail should be delivered. |
| `delivery_point_bar_code_check` | `dateTime` | A Delivery Point Barcode (DPBC) check is a verification process used to ensure the accuracy and validity of a Delivery Point Barcode, which is a barcode used by the United States Postal Service (USPS) to automate the sorting and delivery of mail. |
| `full_address` | `string` | A full address includes all the necessary information to identify and locate a specific location or recipient. |
| `highway_contract_route_identifier` | `string` | A highway contract route (HCR) identifier is a unique code assigned to a specific highway contract route used for mail transportation by the United States Postal Service (USPS). |
| `last_updated_datetime` | `dateTime` | Last_updated_datetime describes when an address was last updated in a system. |
| `mail_stop_code` | `string` | A mail stop code, also known as a mail code or department code, is a unique identifier used within an organization to facilitate the sorting and delivery of internal mail or correspondence. It is primarily used in large organizations where there may be multiple departments or units located in the same physical location. |
| `plus_four_postal_code` | `string` | A postal code plus four, also known as a ZIP code plus four (in the United States) is a numerical extension to a postal code. |
| `post_office_box_identifier` | `string` | A post office box identifier refers to the unique number or alphanumeric code assigned to an individual or organization's post office box (PO Box) for receiving mail at a post office facility. |
| `postal_code` | `string` | A postal code, also known as a ZIP code (in the United States) or postcode (in many other countries), is a numerical code used by postal services to identify specific geographic areas for efficient mail sorting and delivery. |
| `rural_route_box_identifier` | `string` | A rural route box identifier, also known as an RR box identifier, is a number or alphanumeric code assigned to a mailbox or mail receptacle on a rural route. |
| `rural_route_identifier` | `string` | A rural route identifier, also known as an RR identifier, is a number or alphanumeric code assigned to a specific rural route for mail delivery. In rural areas, where homes and businesses are often spread out over long distances, a rural route is a designated path followed by mail carriers to deliver mail to multiple addresses along that route. |
| `sequence_number` | `string` | A license sequence number is a unique numerical identifier assigned to license within a specific sequence or order. It is used to indicate the position or sequence of a license within a given range or list. |
| `state_code` | `string` | State code is a code that represents the state in which the address is located. |
| `state_name` | `string` | State name refers to the name of the state in which the address is located. |
| `street_name` | `string` | A street name is the name of a street on which an address is located. |
| `street_post_directional_text` | `string` | Street post directional text refers to the directional indicator or suffix added to a street name to provide additional information about the direction or orientation of the street segment. It helps to clarify the position of a particular street in relation to other streets or landmarks in a given area. |
| `street_pre_directional_text` | `string` | Street pre directional text refers to the directional indicator or prefix added to a street name to provide additional information about the direction or orientation of the street segment. It helps to clarify the position of a particular street in relation to other streets or landmarks in a given area. |
| `street_primary_number` | `string` | Street primary number refers to the numerical part of a street address that indicates the specific location or position of a building or property along a street. |
| `street_suffix` | `string` | A street suffix, also known as a street type or street name suffix, is a word or abbreviation that follows the street name in an address, indicating the type or category of the street (e.g., Drive, Circle, Boulevard). |
| `unit_identifier` | `string` | A unit identifier is a reference to the specific unit, suite, apartment, or other secondary identifier associated with an address. It is used to differentiate individual units within a larger building or complex. |
---
# credit
# credit
A credit record for a person: scores, their models, and the liabilities the report carries.
Credit refers to information about an individual's or organization's creditworthiness: their ability to borrow money with the promise of repaying the debt later, the amount of money they've borrowed but haven't repaid, and their history of repaying debt according to credit agreements.
## Why it matters
Bureaus disagree in shape, not only in value. Score model naming, liability classification and joint-borrower treatment all differ between them, and this class is the single form all of it lands in.
A score is meaningless without its model, so the two travel together rather than a bare number being stored. That is the difference between a record that can be compared across bureaus and one that cannot.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `credit_identifier` | `string` | A credit identifier is a unique identifier for the credit record of an individual or organization. |
| `credit_score` | `integer` | A credit score is a numerical representation of a person's creditworthiness based on their credit history. It's a three-digit number that ranges from 300 to 850, with higher scores indicating better creditworthiness. |
## Referenced by
- `person`
- `person_credit`
---
# document
# document
A document in the transaction: its type, its contents once extracted, and what it evidences.
A document is a written or printed record that contains information, data, or instructions in a fixed form that can be stored, transmitted, or communicated.
## Why it matters
The model covers the document types the industry produces rather than a generic file record — the loan application and its coborrower variant, tax returns and their schedules, wage statements, the loan estimate, closing data and the preapproval letter each have a recorded mapping into this model.
That is what makes an extracted document usable rather than merely stored: the fields land in the same classes a directly-supplied value would, so a downstream step cannot tell whether a figure was typed or read off a page — except by the source recorded against it.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `document_mime_type` | `enumeration` | A document MIME type, or Multipurpose Internet Mail Extension type, is a standard way of identifying the format of a document based on its content. It is used by web servers to communicate the file format to a web browser, allowing the browser to properly display or handle the document. `application_json``application_Id_json``application_xml` |
| `document_name` | `string` | A document name is a title or label given to a document to identify it and distinguish it from other documents. |
| `document_type` | `enumeration` | Document type refers to the classification or categorization of a document based on its purpose, content, or format. `abstract_notice_agreement``abstract_of_judgment``achdebit_authorization``acknowledgment_of_notice_of_right_to_cancel``affidavit_of_death``affidavit_of_lost_note``affiliated_business_arrangement_disclosure``airport_noise_pollution_agreement``alternative_request_for_agreement_of_short_sale``amendatory_clause``amortization_schedule``application_disclosure``application_disclosure_additional_credit_and_debt``appraisal_recertification``appraisal_report``appraisal_report_desktop``appraisal_report_exterior_only``appraisal_report_interior_exterior``appraisal_review``appraisal_review_exterior_only_inspection_with_value_opinion``appraisal_review_exterior_only_without_value_opinion``appraisal_review_interior_exterior_inspection_with_value_opinion``appraisal_review_interior_exterior_without_value_opinion``appraisal_review_no_inspection_with_value_opinion``appraisal_review_request``appraisal_review_without_value_opinion``approval_letter``arm_disclosure``articles_of_incorporation``assignment``assignment_assignment_of_deed_of_trust``assignment_assignment_of_mortgage``assignment_assignment_of_rents``assignment_assignment_of_trade``assignment_blanket_assignment``assignment_cooperative_assignment_of_proprietary_lease``assumption_agreement``assurance_of_completion``attestation_of_damage_to_property``attorney_in_fact_affidavit``attorneys_opinion_letter``automated_underwriting_feedback``automated_valuation_report``automated_valuation_report_with_inspection``avm_feedback``bailee_letter``balance_transfer_authorization_notice``balloon_refinance_disclosure``bank_deposit_slip``bank_statement``bank_statement_401_k``bank_statement_checking_account``bank_statement_mutual_fund_account``bank_statement_saving_account``bank_statement_stock_account``bankruptcy_discharge_notice``benefit_plan_distribution_statement``benefit_plan_distribution_statement_401_k``benefit_plan_distribution_statement_annuity``benefit_plan_distribution_statement_pension``benefit_plan_distribution_statement_trust``bid``birth_certificate``bond_certificate``borrower_acknowledgment_of_property_condition``borrower_authorization_to_release_information``borrower_correspondence , borrower_correspondence_gap_in_employment``borrower_correspondence_letter_of_explanation``borrower_correspondence_letter_of_intent``borrower_correspondence_qualified_written_request``borrower_correspondence_trailing_spouse``borrower_lien_affidavit``borrowers_certification``borrowers_contract_with_respect_to_hotel_and_transient_use_of_property``breach_notice``broker_disclosure_statement``broker_price_opinion``broker_price_opinion_desktop``broker_price_opinion_exterior_inspection``builders_certification``builders_certification_builder_certification_of_plans_and_specifications``builders_certification_builders_certificate``builders_certification_property_inspection``builders_certification_termite_treatment``building_permit``business_license``buydown_agreement``buying_your_home_settlement_costs_and_helpful_information``caivrs_authorization``cancellation_of_listing``check``checklist``child_support_verification``close_line_of_credit_request``closing_disclosure``closing_disclosure_alternate_form``closing_disclosure_borrower_only``closing_disclosure_model_form``closing_disclosure_seller_only``closing_instructions``collection_register``comparative_income_analysis``compliance_agreement``compliance_inspection_report``conditional_commitment``condominium_occupancy_certificate``conservator_and_guardianship_agreement``construction_cost_breakdown``consumer_handbook_on_arm``conversion_option_notice``conveyance_deed``conveyance_deed_bargain_and_sale_deed``conveyance_deed_quit_claim_deed``conveyance_deed_warranty_deed``conveyance_tax_form , cooperative_bylaws``cooperative_operating_budget``cooperative_proprietary_lease``cooperative_recognition_agreement``cooperative_stock_certificate``cooperative_stock_power``cosigner_notice``counseling_certification``counseling_certification_home_retention``counseling_certification_homeownership``counseling_checklist_for_military_homebuyers``credit_card_authorization``credit_insurance_agreement``credit_report``credit_reporting_adjustment``customer_identification_verification` |
| `staircase_blob_identifier` | `string` | Blob identifier refers to a unique identifier assigned to a binary large object (BLOB), which is a large binary data structure that can be used to store documents and other types of data. BLOBs are often used in mortgage banking systems to store important loan documents such as loan applications, credit reports, income verification documents, and property appraisals. |
| `staircase_document_category_type` | `enumeration` | A Staircase document category type indicates if the source of the document category is Staircase or a Staircase partner. `Staircase``Partner` |
## Referenced by
- `employment_income`
---
# employment_income
# employment_income
The link between an employment record, the income it produced, and the document that evidenced it.
Employment_income describes properties related to income received from employment.
## Why it matters
Three-way rather than two-way, and the third leg is the point. An income figure is attributable to an employment, and it was evidenced by something — a paystub, a tax form, a verification response — and the record of which document supported which figure is what an underwriter needs when a file is questioned.
Holding the evidence on the relationship rather than on the income record keeps the same income figure usable when a second document corroborates it. Two documents supporting one figure is two of these, not a document field overwritten.
## In practice
Employment writes these as it normalises a vendor response, which is why a returned income figure can always be traced back to the employer and the artifact it came from.
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_document` | `document` | An income document is a document that provides information about an individual's income. These documents are typically required for various financial and legal purposes, such as applying for a loan, filing taxes, or verifying employment. |
| `has_employment` | `employment` | As part of employment, a person or organization will receive income. Income is money that a person or organization earns or receives on a regular basis from various sources. Employment refers to the state of being employed, meaning a person has a job or occupation and is receiving compensation for their work. |
| `has_income` | `income` | A person has income. Income is money that a person or organization earns or receives on a regular basis from various sources. |
---
# employment
# employment
An employment relationship for a person: employer, position, dates and status.
Employment refers to the state of being employed, meaning a person has a job or occupation and is receiving compensation for their work.
## Why it matters
Employment and income are separate classes because the questions are separate. An employer confirms a person works there; a payroll record says what they were paid; a guideline asks how long they have done so. The three come from different vendors with different coverage.
Dates carry the weight. Continuity of employment across a period is what a guideline tests, so start and end dates are first-class rather than derived from a current-employer flag.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `current_employment_indicator` | `boolean` | A current_employment indicator identifies if a person is currentlly employed. Current employment refers to an individual's present or ongoing employment status. It indicates that the individual is currently working for an employer and is receiving compensation for their work. |
| `employment_identifier` | `string` | An employment identifier is a unique identifier assigned to an individual by their employer for the purpose of tracking their employment information. It is typically a numerical or alphanumeric code that is used to identify the employee within the employer's human resources management system. |
| `employment_job_description` | `string` | An employment job description outlines the duties, responsibilities, qualifications, and requirements of a specific job or role within an organization. |
| `employment_monthly_income_amount` | `integer` | Employment monthly income amount refers to the amount of money earned by an individual through employment activities in a month. This income includes the gross salary or wages paid by an employer, as well as any bonuses, commissions, or other forms of compensation received by the employee during that period. |
| `has_employer` | `company` | A person who holds a job has an employer. An employer is a person, company, organization, or entity that hires and employs workers to perform specific tasks or jobs in exchange for payment. |
| `start_date` | `date` | An employment start date refers to the date on which an individual begins working for an employer in a new job or position. |
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_employee` | `person` | A person, company, organization or entity that hires and employs workers has employees. An employee is an individual who works for an employer in exchange for payment, usually in the form of wages or salary. Employees are hired to perform specific tasks or jobs and are under the supervision and direction of the employer. |
## Referenced by
- `employment_income`
---
# fee
# fee
A charge in the transaction: its kind, amount, payer, and the section of the disclosure it belongs to.
Fee refers to a charge or cost associated with obtaining and servicing a mortgage loan.
## Why it matters
Fees are modelled by their disclosure treatment rather than by who invoices them, because that treatment is what the regulation constrains. Which section a fee falls in determines whether it counts toward a tolerance and whether a change requires a redisclosure.
The computation over this class is Fee, including the comparison between successive disclosures, which is a computation over a pair rather than a difference a reader is left to take.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `actual_payment_amount` | `decimal` | Fee actual payment amount refers to the monetary amount paid to satisfy a fee. |
| `assessed_amount` | `decimal` | Fee assessed amount refers to the monetary amount assessed to satisfy a fee. |
| `assessed_date` | `date` | Fee assessed date refers to the date a fee payment was assessed. |
| `description` | `decimal` | A company description is a brief summary or overview of a business. It typically includes information such as the company's industry, size, products or services offered, target market, and mission statement. |
| `payment_paid_date` | `date` | Fee payment paid date refers to the date a fee payment was made. |
| `type` | `enumeration` | Fee type refers to the categorization or classification of a fee based on its nature or purpose. `homeowners_association_dues``homeowners_association_service_fee``homeowners_association_special_assessment` |
---
# finance_relation
# finance_relation
A person's financial position: the assets and debts attached to them, each as its own reference.
Finance_relation contains information about financial assets and debts related to a person.
## Why it matters
One person, and references to a property, a mortgage, a loan, a lease, a rent, an automobile, an insurance policy and a tax record, plus a stage value, a feedback value and a main-applicant indicator.
Every item is a reference rather than an embedded field, which is what keeps the class from becoming a wide record that has to be widened again for the next kind of asset. A new asset type is a new class and one more relationship, not a schema change on every consumer.
## In practice
The stage value is what makes the record readable mid-application: a position gathered so far is a valid position, not an incomplete one.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `feedback_value` | `enumeration` | Feedback value refers to feedback received from the customer. `Rate Is Too High``Payment Is Too High``Taxes Surprised Me``I Want To Think On It` |
| `has_automobile` | `automobile` | An automobile is a road vehicle, typically with four wheels, powered by an internal combustion engine or electric motor and able to carry a small number of people. A person can have an automobile. If the person owns the automobile outright, it is a financial asset. If the person has taken out a loan to purchase the automobile, it is a financial debt because it represents money that they have borrowed from the lender and must repay over time. |
| `has_lease` | `lease` | A person can have a lease, which is considered financial debt. A lease is a legally binding agreement between two parties, typically a landlord (lessor) and a tenant (lessee), in which the lessor agrees to rent out a property or asset to the lessee for a specified period of time and under certain conditions. |
| `has_main_applicant` | `boolean` | The main applicant on a loan application is the person who is financially responsible for repaying the loan. This person is also known as the borrower or the applicant. |
| `has_rent` | `rent` | A person can owe rent, which is considered financial debt. Rent refers to payments made by a tenant to a landlord in exchange for the use and occupancy of a property or space. Rent can be paid for a variety of properties, including apartments, houses, offices, retail spaces, and more. |
| `has_stage_value` | `enumeration` | The stage value refers to an applicant's stage in the home buying process. For example, a borrower might be 'just looking' or 'ready to buy.' `Learning``Browsing``Ready to Buy``Already PreApproved``In Contact``Rate Shopping` |
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_insurance` | `insurance` | A person who owns property, an automobile or another financial asset may also have insurance on that asset, which is considered financial debt. Insurance is a policy that provides financial protection for physical assets like homes, or financial assets like mortgages. |
| `has_loan` | `loan` | A mortgage application has a loan. A loan in a mortgage application refers to the amount of money that a borrower is requesting from a lender to purchase a property. When a borrower submits a mortgage application, they specify the amount of money they need to borrow to purchase the property. |
| `has_mortgage` | `loan` | A mortgage is a loan that is taken out to purchase a property, typically a home. A person can have a mortgage, which is considered financial debt. |
| `has_person` | `person` | A member is also a person. |
| `has_property` | `property` | Property is a piece of land and any structures or improvements that are permanently attached to it. In the context of property tax, a property can have a tax levied against it. The tax is usually assessed and collected by local governments, such as cities or counties, and is used to fund local services such as schools, police and fire departments, road maintenance, and other community services. |
| `has_tax` | `tax` | A person who owns a financial asset may have to pay taxes on the asset. Taxes are fees levied by federal, state, and local governments on income, goods and services, and property, among other things. In the context of finance, tax is considered a financial debt. |
---
# income
# income
Income attributed to a person: amount, frequency, the period it covers, and its kind.
Income is money that a person or organization earns or receives on a regular basis from various sources.
## Why it matters
Income is separated by kind because qualification treats the kinds differently. Base salary, bonus, overtime, commission, self-employment and rental income are averaged over different periods and discounted at different rates, and a single amount field would make those rules unexpressible.
Verified income and qualifying income are also separate ideas — one is what a vendor reported, the other is what a guideline permits counting. See Income for the calculation layer.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `annual_income` | `decimal` | Annual income refers to the yearly financial earnings of an individual or organization. |
| `bonus_income_amount` | `integer` | Bonus income refers to an additional amount of money that an individual receives on top of their regular salary or wages. This type of income is usually provided as a reward or incentive for achieving specific goals or milestones, such as meeting sales targets or completing a project ahead of schedule. |
| `income_amount` | `integer` | Income amount refers to the total amount of money that an individual or entity receives during a specified period. |
| `income_description` | `string` | A description of income is a statement or summary that provides details about an individual's or entity's sources of income. It typically includes information about the type of income, such as wages, salaries, commissions, bonuses, dividends, interest, or capital gains. |
| `income_identifier` | `string` | An income identifier is a unique identifier for the income record of an individual or organization. |
| `income_pay_frequency_type` | `enumeration` | Income pay frequency refers to the frequency at which an individual or entity receives payment for their work or services. `Weekly``Biweekly``Monthly``Yearly` |
| `income_type` | `enumeration` | Income type refers to the specific category or source of income earned by an individual or entity, such as earned, investment or rental income. `Base``Bonuses``Commissions``Overtime``Military Base Pay``Military Rations Allowance``Military Flight Pay``Military Hazard Pay``Military Clothes Allowance``Military Quarters Allowance``Military Prop Pay``Military Overseas Pay``Military Combat Pay``Military Variable Housing Allowance``Contract Basis``Other` |
| `income_year` | `string` | Income year refers to the year in which an individual or entity received income. |
| `other_income_amount` | `integer` | Other income refers to any additional income that an individual receives beyond their regular salary or wages, but that is not categorized as bonus income or overtime income. |
| `overtime_income_amount` | `integer` | Overtime income refers to the additional pay that an employee receives for working beyond their regular work hours or scheduled shift. Overtime pay is typically paid at a higher rate than regular pay in recognition of the additional time and effort required. |
## Referenced by
- `employment_income`
- `person`
- `person_income`
---
# insurance
# insurance
Insurance is a policy that provides financial protection for physical assets like homes, or financial assets like mortgages.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `base_loan_amount` | `decimal` | The base loan amount is the amount of money that a borrower is approved to borrow from a lender before any additional fees or charges are added to the loan. It is the principal amount of the loan and does not include any interest, closing costs, or other fees. |
| `borrower_requested_interest_rate_percent` | `decimal` | A borrower-requested interest rate percent is the interest rate that the borrower has requested for the mortgage. Mortgage interest rate is the percentage of the loan amount that the borrower will pay to the lender as interest over the life of the loan. It is usually expressed as an annual percentage rate (APR) and can vary depending on a number of factors, such as the borrower's credit score, the size of the down payment, and the type of loan. |
| `coverage_amount` | `decimal` | The coverage amount refers to the maximum amount of money that an insurance policy will pay out to cover damages or losses to a property. This amount is typically set by the policy holder when they purchase the insurance policy, and it represents the estimated cost to repair or replace the property in the event of damage or loss. |
| `coverage_description` | `string` | A coverage description is a detailed explanation of what is covered under the policy and the circumstances under which a claim can be made. The coverage description will typically include information on the types of perils or events that are covered, as well as any exclusions or limitations that apply to the coverage. |
| `deductible_amount` | `decimal` | A deductible amount refers to the portion of a claim that the policyholder is responsible for paying out of pocket before the insurance company will start to cover the costs of the claim. Deductibles are typically expressed as a specific dollar amount or as a percentage of the total insured value of the property. |
| `deductible_description` | `string` | A deductible description is a detailed explanation of what the policyholder is responsible for paying out of pocket before the insurance company will start to cover the costs of the claim. |
| `escrow_indicator` | `boolean` | The escrow_indicator identifies mortgages where the lender sets aside a portion of the monthly mortgage payment to cover the cost of insurance premiums. When a borrower takes out a mortgage loan to purchase a home, the lender may require the borrower to escrow, or set aside, funds to cover the cost of property insurance, such as homeowners insurance or hazard insurance. |
| `five_year_cost_comparison_amount` | `decimal` | The five year cost comparison amount is the amount resulting from a calculation that compares the total cost of two different mortgages over a five-year period. It takes into account the interest rate, loan amount, and other costs associated with the mortgage, such as closing costs and fees. To calculate the five year cost comparison, you would take the total cost of each mortgage over a five-year period, including all principal, interest, and fees, and compare them to determine which option is more cost-effective. |
| `force_placed_by_servicer_indicator` | `boolean` | A forced_place_by_servicer_indicator identifies mortgages where a mortgage servicer (lender) placed insurance on a property because the borrower (property owner) did not have sufficient insurance coverage in place. In a mortgage agreement, the lender may require the borrower to maintain adequate insurance coverage on the property to protect against damage or loss. If the borrower fails to maintain this insurance coverage, the lender may have the right to force place insurance to protect their interest in the property. |
| `housing_cost_over_five_years_amount` | `decimal` | The housing cost over five years amount is the amount resulting from the calculation that adds up all of the costs associated with owning a home over a five-year period. This includes not only the mortgage payment, but also property taxes, insurance premiums, maintenance costs, and any other expenses related to home ownership. To calculate the housing cost over five years, you would first determine the total cost of the mortgage payment over that period of time, including principal and interest. Next, you would add in the cost of property taxes and insurance premiums, which are typically paid on an annual basis but can be divided by five to get an average annual cost. You would also factor in an estimate for maintenance and repair costs, which can vary depending on the age and condition of the home. |
| `investor_program_name_type` | `enumeration` | An investor program name type refers to a type of loan that is designed for real estate investors. These programs are often offered by lenders and are designed to meet the specific needs of investors who are looking to purchase, renovate, or refinance investment properties. `calpers``other``payment_power``prime_rate_plus``settle_america` |
| `investor_program_name_type_other_description` | `string` | An investor program name type (other) description refers to a description for a non-standard type of loan designed for real estate investors. Since this program type is non-standard, it is typically designated as an 'other' type. |
| `loan_identifier_type` | `enumeration` | A loan identifier type is a unique identification code assigned to a mortgage loan by a lender or a loan servicer. The loan identifier is used to track the loan throughout its life cycle, from origination to servicing, and can be used to help identify the loan in various systems and databases. Some loan identifier types being used in the mortgage industry include a lender/servicer-assigned identifier, a universal loan identifier (ULI), Fannie Mae loan number and Freddie Mac loan number. `agency_case``investor_commitment``investor_contract``investor_loan``investor_workout_case``lender_case``lender_loan``loan_price_quote``mers_min``mi_rate_quote``new_servicer_loan``other``pool_issuer_loan``price_response``seller_loan``servicer_loan``servicer_workout_case``subservicer_loan``wholesale_lender_loan``universal_loan` |
| `loan_identifier_type_other_description` | `string` | A loan identifier type (other) description refers to a description for a non-standard type of loan identifier. Since the identifier is non-standard, it is typically designated as an 'other' type. |
| `policy_cancellation_date` | `date` | An insurance policy cancellation date refers to the date on which an insurance policy is terminated or cancelled by either the insurance company or the policyholder. |
| `policy_effective_date` | `date` | An insurance policy effective date is the date on which the insurance coverage begins. It is the date on which the policyholder's coverage is considered to be in force and the insurance company is obligated to pay for any covered losses or damages that occur after that date. |
| `policy_expiration_date` | `date` | An insurance policy expiration date is the date on which an insurance policy ends and coverage under the policy ceases. The expiration date is typically specified in the policy documentation and is often one year from the date the policy was originally purchased or renewed. |
| `policy_identifier` | `string` | An insurance policy identifier is a unique code or number that is assigned to an insurance policy to identify it within an insurance company's system. This identifier is used to track policy information, premiums paid, claims filed, and other important details related to the policy. |
| `policy_renewal_date` | `date` | An insurance policy renewal date is the date on which an insurance policy comes up for renewal. Insurance policies typically have a fixed term, such as one year, and must be renewed at the end of that term to remain in effect. |
| `premium_amount` | `decimal` | An insurance policy premium amount refers to the amount of money that an individual or business must pay to an insurance company in exchange for insurance coverage. |
| `rate_quote_all_product_indicator` | `boolean` | The rate_quote_all_product_indicator identifies loans where the mortgage lender has provided a quote that includes interest rates and other terms for all of their financial products that may be available to a borrower. A rate quote typically includes information such as the interest rate, any fees or charges associated with the product, the term of the loan and the monthly payment amount. |
| `rate_quote_product_comparison_indicator` | `boolean` | The rate_quote_product_comparison_indicator identifies loans where the mortgage lender has provided a rate quote that allows borrowers to compare different mortgage products based on the interest rates and fees associated with each loan option. |
| `rate_quote_type` | `enumeration` | A rate quote type is a type of estimate provided by a lender that outlines the potential interest rate and other costs associated with a mortgage loan. It is often given to borrowers who are in the process of shopping for a mortgage and are looking for information on the rates and fees that may apply to a loan. `detail``other``estimated` |
| `rate_quote_type_other_description` | `string` | A rate quote type (other) description refers to a description for a non-standard type of rate quote. Since this rate quote type is non-standard, it is typically designated as an 'other' type. |
| `required_indicator` | `boolean` | The required_indicator indicates that the lender requires the borrower to carry insurance for the property. |
| `second_deductible_amount` | `decimal` | A second deductible amount is the highest amount a property owner will have to pay out of pocket if a specific kind of loss or damage occurs. Typically there is typically only one deductible amount that applies to each covered loss. However, in some cases, a policy may include multiple deductibles for different types of losses or damage. For example, a policy may have a separate deductible for wind damage, hail damage, and flood damage. In this case, the policyholder would be responsible for paying the applicable deductible for each type of damage that occurred. |
| `second_deductible_description` | `string` | A second deductible description is a detailed explanation of the conditions under which a second deductible would apply. |
| `service_payer_type` | `enumeration` | A servicer payer type refers to the type of entity that is responsible for making payments on a loan or other financial obligation on behalf of another party. In the context of a mortgage, the servicer payer type is typically the borrower, who is responsible for making monthly payments to the loan servicer. `borrower``lender` |
| `subordinate_financing_is_new_indicator` | `boolean` | The subordinate_financing_is_new_indicator indicates that new secondary loan is secured by the same collateral as the primary loan. This means that if the borrower defaults on the primary loan, the subordinate lender has a secondary claim on the collateral after the primary lender. |
| `the_best_quote_indicator` | `boolean` | The the_best_quote_indicator indicates that a borrower has received a best quote, or most favorable loan offer available, from a lender. When a borrower is shopping for a loan, they may receive multiple loan offers with different interest rates, terms, and fees. The best quote is the one that offers the lowest interest rate, the most favorable terms, and the lowest fees. |
| `third_deductible_amount` | `decimal` | A third deductible amount is the highest amount a property owner will have to pay out of pocket if a specific kind of loss or damage occurs. Typically there is typically only one deductible amount that applies to each covered loss. However, in some cases, a policy may include multiple deductibles for different types of losses or damage. For example, a policy may have a separate deductible for wind damage, hail damage, and flood damage. In this case, the policyholder would be responsible for paying the applicable deductible for each type of damage that occurred. |
| `third_deductible_description` | `string` | A third deductible description is a detailed explanation of the conditions under which a third deductible would apply. |
## Referenced by
- `finance_relation`
---
# loan
# loan
A financing agreement between a lender and a borrower, with its terms, amounts, rates and schedule.
A loan is a financial agreement between a lender and a borrower, in which the lender provides the borrower with a certain amount of money or assets, and the borrower agrees to repay the loan over time with interest and/or fees.
## Why it matters
The loan is the spine of the transaction. Parties reach it through relationship classes rather than through fields on it, which is what allows a loan to carry several borrowers, several properties and a changing set of participants without the class changing shape.
Amounts and percentages are decimal by rule, and every property carrying money or a rate says so in its own name — the suffix law is what makes a property's type legible before its definition is read.
## In practice
This class is the origination side. The `loan` in the property model is the recorded side: what a deed index shows filed against a parcel, which reflects what was recorded rather than a current balance. They are different classes in different models for that reason.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `amortization_type` | `enumeration` | Loan amortization type refers to the method used to calculate and pay off a loan over time. The two most common types of loan amortization are fully amortizing and partially amortizing. In a fully amortizing loan, the borrower makes regular payments (usually monthly) that include both principal and interest. Each payment reduces the principal balance of the loan, and over time the loan is gradually paid off in full. In a partially amortizing loan, the borrower makes regular payments that include both principal and interest, but the payments are not large enough to fully pay off the loan by the end of its term. As a result, at the end of the loan term, the borrower must either make a balloon payment to pay off the remaining balance, refinance the loan, or enter into another agreement with the lender. `adjustable_rate``fixed``gem``gpm``graduated_payment_arm``other``rate_improvement_mortgage``step` |
| `appraisal_value` | `decimal` | Appraisal value indicates the estimated fair market value of a property determined by a professional appraiser. The appraisal process involves a comprehensive evaluation of the property, including its physical characteristics, location, and current market conditions. The appraiser will consider factors such as the size and layout of the property, the condition of the interior and exterior, any upgrades or renovations made to the property, and comparable sales in the area. |
| `base_ltv_value` | `decimal` | Base LTV (Loan-to-Value) ratio is the ratio between the total amount of the loan and the appraised value of the asset that is being used as collateral for the loan. The Base LTV is the initial ratio established at the time of the loan origination, which determines the maximum loan amount that can be borrowed based on the value of the collateral. |
| `borrower_paid_mi` | `boolean` | Borrower-paid mortgage insurance (BPMI) is a type of insurance that mortgage borrowers can purchase to protect their lender in the event that they default on their mortgage payments. BPMI is typically required for borrowers who make a down payment of less than 20% of the home's purchase price. BPMI is different from other types of mortgage insurance because the borrower is responsible for paying the premiums, rather than the lender. The premiums can be paid upfront as a lump sum, or they can be added to the monthly mortgage payment. |
| `buydown_amount` | `decimal` | A mortgage buydown is a financing technique in which the borrower or a third party pays an upfront fee to lower the interest rate on a mortgage loan for a period of time, typically the first few years of the loan term. The amount of the buydown is typically calculated as a percentage of the loan amount. The mortgage buydown amount is the total amount of money that is paid upfront to lower the interest rate on the mortgage loan. |
| `buydown_type` | `enumeration` | A mortgage buydown is a type of mortgage financing in which the borrower or a third party pays an additional fee, known as points, to the lender in exchange for a lower interest rate on the mortgage loan. The buydown can be a temporary or permanent reduction of the interest rate on the mortgage loan. There are two main types of buydowns: temporary and permanent. `None``OneOne``OneZero``ThreeTwoOne``TwoOne` |
| `day_one_certainty_indicator` | `boolean` | Day 1 Certainty is a program offered by Fannie Mae, a government-sponsored enterprise (GSE), to help lenders streamline the mortgage loan origination process and reduce risk. The program aims to provide lenders with greater confidence in the underwriting process and reduce the need for additional documentation and manual processes. |
| `downpayment_amount` | `integer` | Down payment amount refers to the amount of money that a borrower pays upfront to purchase a property, before obtaining a mortgage loan. The specific amount required can vary depending on factors such as the borrower's creditworthiness, the type of loan, and the lender's requirements. In general, a larger down payment can help to reduce the amount of the mortgage loan needed and can lead to lower monthly payments and interest charges over the life of the loan. |
| `downpayment_percentage` | `decimal` | Down payment percent is the percentage of the purchase price of a property that a borrower pays upfront as a down payment towards the mortgage loan. The down payment percentage is an important factor in determining the loan-to-value (LTV) ratio, which is the ratio of the loan amount to the appraised value of the property. A higher down payment percentage means a lower loan amount and a lower LTV ratio, which may result in a lower interest rate and better loan terms. |
| `dti_value` | `integer` | Debt-To-Income (DTI) ratio is a financial ratio that compares a borrower's total monthly debt payments to their gross monthly income. It is used by lenders to evaluate a borrower's ability to repay a loan, particularly a mortgage loan. To calculate the DTI ratio, the borrower's total monthly debt payments, including things like credit card payments, car payments, student loans, and other loan payments, are divided by their gross monthly income (pre-tax income). The resulting ratio is expressed as a decimal. A DTI ratio of .43 or lower is generally considered a good target for most borrowers. |
| `end_date` | `date` | End date refers to the date on which a rental agreement or lease ends and the tenant is no longer obligated to pay rent for the property or space. This date is typically specified in the rental agreement or lease, and it marks the end of the tenant's legal right to occupy the property. |
| `interest_only` | `boolean` | Interest-only in a loan is a type of loan where the borrower is required to pay only the interest on the loan during the initial period of the loan, which is typically for a fixed number of years. During the interest-only period, the borrower is not required to pay down the principal amount of the loan, which means that the loan balance remains the same. After the interest-only period ends, the borrower is required to make full payments that include both principal and interest until the loan is fully paid off. This means that the borrower will have to make higher payments compared to the interest-only period, as the principal amount must be paid down over the remaining loan term. |
| `loan_amount` | `integer` | Loan amount refers to the total amount of money that a borrower borrows from a lender to purchase a property. This amount is typically based on the purchase price of the property, minus any down payment that the borrower is able to make. |
| `loan_identifier` | `string` | A loan identifier, also known as an MLI or loan number, is a unique identification number that is assigned to a specific mortgage loan. It is typically used by lenders and servicers to track and manage mortgage loans throughout the life of the loan. |
| `loan_purpose` | `enumeration` | Loan purpose refers to the reason or purpose for which a borrower is obtaining a loan. When applying for a loan, borrowers are typically required to specify the purpose of the loan to the lender. The loan purpose helps the lender assess the borrower's creditworthiness and determine whether the loan is a good fit for the borrower's needs. `mortgage_modification``other``purchase``refinance` |
| `loan_role_type` | `enumeration` | Loan role type helps lenders understand a borrower's ability to repay a loan and determine loan terms and conditions. There are three types of loan roles: subject, related and historical. A subject loan is the loan that is being evaluated or underwritten by the lender. A related loan is a loan that is related to the subject loan in some way, such as a second mortgage or a home equity line of credit (HELOC) that is taken out on the same property. A historical loan is a loan that has already been repaid or closed. `historical``subject_loan``related_loan` |
| `loan_status` | `enumeration` | Loan status refers to the current state or condition of a loan. It indicates whether the borrower is up-to-date with their payments, in default, or in some other stage of the loan process. `lead``processing``pre_qualify``registered``pre_approval``application_taken``broker_initial_submission``prospect``initial_submission``approved``suspended``pre_deny``broker_condition_submission``condition_submission``clear_to_close``denied``withdrawn``not_accepted``incomplete``rescinded``closed``funded``post_closing``in_shipping``purchased``servicing` |
| `loan_status_date` | `date` | Loan status date indicates the date on which the status of a loan was last updated or changed. It is the date when the loan's status was evaluated and recorded by the lender or servicer, and can indicate whether the borrower is up-to-date on their payments, delinquent, or in default. |
| `loan_term` | `integer` | Loan term refers to the length of time over which a borrower must repay a loan to the lender. It is typically expressed in months or years and is agreed upon at the time the loan is originated. |
| `loan_type` | `enumeration` | Loan type refers to the specific type of loan that a borrower obtains from a lender, such as a personal loan, auto loan, or student loan. The loan type determines the terms and conditions of the loan, including the interest rate, repayment period, and the amount borrowed. `conventional``fha``va` |
| `ltv_value` | `decimal` | Loan-To-Value (LTV) ratio is a financial ratio that compares the amount of the loan to the appraised value of the property being purchased or refinanced. To calculate the LTV ratio, the loan amount is divided by the appraised value of the property. The resulting ratio is expressed as a decimal. In general, a lower LTV ratio is considered better, as it indicates that the borrower has a larger equity stake in the property, and may be less likely to default on the loan. |
| `monthly_payment` | `decimal` | A mortgage monthly payment is the amount of money that a borrower pays each month to repay the mortgage loan, which includes both the principal and interest on the loan. In addition to the principal and interest, the mortgage monthly payment may also include other expenses such as property taxes, homeowners insurance, and mortgage insurance, depending on the loan type and requirements. These additional expenses are often collected and held in an escrow account by the lender, who then pays them on behalf of the borrower. |
| `mortgage_type` | `enumeration` | Mortgage type refers to the specific type of mortgage loan that a borrower obtains to finance the purchase or refinance of a property. There are several different types of mortgage loans, each with its own set of features, eligibility requirements, and interest rates. `conventional``fha``local_agency``other``public_and_indian_housing``state_agency``usda_rural_development``va` |
| `mortgage_value` | `decimal` | Mortgage value refers to the amount of money that is borrowed by a borrower to purchase or refinance a property using a mortgage loan. It is the principal amount of the mortgage loan that is used to finance the purchase of the property. The mortgage value is typically determined by the purchase price of the property or its appraised value, whichever is lower. |
| `note` | `string` | A note is a legal document that outlines the terms of the loan between the borrower and lender. It is also known as a promissory note. The note contains the borrower's promise to repay the loan, the interest rate, the repayment terms, and other details about the loan, such as the maturity date and any prepayment penalties. |
| `note_rate_percentage` | `decimal` | Note rate percent refers to the interest rate specified in the promissory note or loan agreement between a lender and borrower. The note rate is the annual percentage rate (APR) that the borrower will pay on the loan amount. |
| `occupancy` | `enumeration` | Occupancy type refers to the way in which a property is used or occupied by its owner or tenant. Occupancy type is used in determining the terms of a mortgage or loan and the level of risk associated with a property. `primary_residence``second_home``investment``other` |
| `prepayment_penalty` | `integer` | A prepayment penalty is a fee charged by some lenders if you pay off your loan before the end of its term. Essentially, it's a penalty for paying off your debt early. Lenders use prepayment penalties to discourage borrowers from paying off their loans too quickly, which can reduce the lender's profits by reducing the amount of interest they can collect. The penalty is usually a percentage of the remaining loan balance or a certain number of months' worth of interest payments. |
| `program_period_type` | `enumeration` | Loan program period type refers to the period of time associated with the loan program. `period_fixed_10_years``period_fixed_15_years``period_fixed_20_years``period_fixed_30_years``period_arm_5_years``period_arm_7_years``period_arm_10_years` |
| `start_date` | `date` | An employment start date refers to the date on which an individual begins working for an employer in a new job or position. |
## Referenced by
- `finance_relation`
- `mortgage_application`
---
# mortgage_application
# mortgage_application
A formal request for a loan: the loan itself, the plan chosen, and the pricing schema it was quoted under.
Mortgage_application describes properties of a mortgage application.
## Why it matters
Three references — the loan, the mortgage plan, and the pricing schema.
The pricing schema reference is the one that repays explanation. A quote is only meaningful against the rules it was produced under, and those rules change. Holding the schema on the application means a quote can be reproduced later rather than recomputed under whatever rules are current, which is the difference between an audit trail and an estimate.
## In practice
Price produces the quote and Approval reads the application when it issues a conditional approval without an underwriter.
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_loan` | `loan` | A mortgage application has a loan. A loan in a mortgage application refers to the amount of money that a borrower is requesting from a lender to purchase a property. When a borrower submits a mortgage application, they specify the amount of money they need to borrow to purchase the property. |
| `has_mortgage_plan` | `mortgage_plan` | A mortgage application has a plan. A mortgage plan in a mortgage application typically refers to the proposed repayment plan for the loan. It outlines how the borrower plans to repay the loan over time, including the amount of each payment, the frequency of payments, and the length of the repayment period. |
| `has_pricing_schema` | `pricing_schema` | A mortgage application has a pricing schema. A pricing schema, also known as a pricing model, is a method used by lenders to determine the interest rate and fees that will be charged to a borrower for a mortgage loan. Pricing schemas take into account a variety of factors that can impact the risk of lending to a particular borrower, including their credit score, income, employment history, debt-to-income ratio, and the size of the down payment. |
---
# mortgage_plan
# mortgage_plan
The financing structure chosen for a loan: its name, its code and its amortisation term.
A mortgage plan is a financial agreement between a borrower and a lender to finance the purchase of a property.
## Why it matters
Four fields — an identifier, a name, a code and an amortisation term. A mortgage application points at one.
The plan is separated from the loan because the same structure is offered to many borrowers, and pricing is quoted against the structure rather than against the file. Best execution runs an eligible-product search across amortisation terms, which is only expressible if the term belongs to a plan that can be compared with other plans.
## In practice
Price selects across plans, and the plan the quote was produced under stays attached to the application afterwards.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `amortization_term` | `string` | Mortgage plan amortization term refers to the specific conditions and schedule for paying off a mortgage loan. The amortization term typically refers to the length of time over which the borrower agrees to repay the loan. |
| `code` | `string` | Mortgage plans can be identified by various codes or identifiers used by lenders, such as loan numbers or mortgage identification numbers (MINs). Loan numbers are typically assigned by the lender and are used to track the specific mortgage loan within the lender's system. Mortgage identification numbers (MINs) are unique nine-digit numbers assigned by the Mortgage Electronic Registration System (MERS) to identify a mortgage loan throughout its life, even if the loan is sold or transferred to another lender. |
| `name` | `string` | A company name is a word or set of words that is used to identify a business entity. It is the primary way in which a company is recognized and distinguished from other entities. |
| `plan_identifier` | `string` | A mortgage plan identifier (MPI) is a unique identification number assigned to a mortgage plan or mortgage agreement. It is a way to track and identify individual mortgage plans, and is typically used by lenders, financial institutions, and government agencies. The MPI is usually a combination of numbers and letters, and is assigned by the lender at the time the mortgage plan is established. It serves as a reference for the lender to identify the specific mortgage plan and keep track of it throughout its life cycle. |
## Referenced by
- `mortgage_application`
---
# payment
# payment
A payment refers to the transfer of money, goods, or services from one party (the payer) to another party (the payee) in exchange for a product, service, or debt settlement.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `days_past_due_count` | `integer` | Payment days past due count is the number of days that a payment has not been received on a specific due date. |
| `frequency_type` | `enumeration` | Payment frequency type indicates how frequently the payment is made. `annual``at_maturity``biweekly``monthly``other``quarterly``semiannual``semimonthly``weekly` |
| `identifier` | `string` | A payment identifier is a unique code or reference number that is used to identify and track a specific payment transaction. It helps in distinguishing one payment from another, especially in situations where multiple payments are being processed simultaneously. |
| `last_paid_amount` | `decimal` | A last paid amount refers to the most recent date on which a payment was made or processed for a particular account or transaction. It signifies the date when the payment was successfully received and recorded by the payee or the entity managing the payment. |
| `last_paid_due_date` | `date` | A last payment paid due date refers to the deadline or the final date by which the most recent payment should have been made to fulfill an outstanding financial obligation. |
| `last_paid_received_date` | `date` | A last payment paid received date refers to the date on which the most recent payment was received by the payee or the entity managing the payment. |
| `late_charge_amount` | `decimal` | A late charge amount, also known as a late fee, is an additional charge imposed on a payer when a payment is not made by the specified due date or within the grace period provided. It is a penalty or fee for late payment. |
| `late_charge_grace_period_days_count` | `integer` | Late charge grace period days count refers to a specified number of days during which a payment can be made after the original due date without incurring a late fee or penalty. It is an allowance granted by the creditor or service provider to give the payer some additional time to submit the payment without facing immediate consequences. |
| `late_charge_maximum_amount` | `decimal` | A late charge maximum amount refers to the maximum fee or penalty imposed by a creditor or service provider when a payment is not made by the due date or within the specified grace period. It represents the maximum additional amount that the payer is required to pay on top of the original payment due in order to cover the cost of the late payment. |
| `late_charge_minimum_amount` | `decimal` | A late charge minimum amount refers to the minimum fee or penalty imposed by a creditor or service provider when a payment is not made by the due date or within the specified grace period. It represents the minimum additional amount that the payer is required to pay on top of the original payment due in order to cover the cost of the late payment. |
| `next_fourth_payment_amount` | `decimal` | Next fourth payment amount refers to the specific value or sum of money that must be transferred or exchanged after the next third payment amount, as part of a payment transaction. |
| `next_payment_amount` | `decimal` | Next payment amount refers to the specific value or sum of money that must next be transferred or exchanged as part of a payment transaction. It represents the monetary value or quantity that the payer will provide next to the payee. |
| `next_payment_due_date` | `date` | A next payment due date refers to the next date by which the next payment must be made to fulfill an outstanding financial obligation. |
| `next_second_payment_amount` | `decimal` | Next second payment amount refers to the specific value or sum of money that must be transferred or exchanged after the next payment amount, as part of a payment transaction. |
| `next_third_payment_amount` | `decimal` | Next third payment amount refers to the specific value or sum of money that must be transferred or exchanged after the next second payment amount, as part of a payment transaction. |
| `payment_amount` | `decimal` | A payment amount is the specific value or sum of money that is being transferred or exchanged as part of a payment transaction. It represents the monetary value or quantity that the payer is providing to the payee. |
## Referenced by
- `tax`
---
# person_credit
# person_credit
The link between a person and a credit record, held as a class of its own.
Person_credit describes properties related to a person's credit.
## Why it matters
The model is flat: no class nests another, and a relationship between two classes is itself a class whose properties join them. This is one of those — it holds a person and a credit record, and nothing else.
A foreign key on the credit record would have been shorter to write and would have cost the two things this shape buys. A person can carry more than one credit record without either side changing, and the relationship can acquire its own attributes later without a migration on either class it joins.
## In practice
A joint application produces several of these against one credit pull, which is the case that makes the separate class earn itself. Credit writes them as it normalises a bureau response.
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_credit` | `credit` | A person can have credit. Credit is a person's ability to borrow money or obtain goods or services with the understanding that they will pay for them later. Credit is typically measured by a credit score, which is a numerical rating that reflects a person's creditworthiness based on their credit history, income, debt-to-income ratio, and other factors. |
| `has_person` | `person` | A member is also a person. |
---
# person_income
# person_income
The link between a person and one income record.
Person_income describes properties related to a person's income.
## Why it matters
A person has income of several kinds at once — base salary, bonus, commission, self-employment, rental — and each is a separate income record because qualification treats the kinds differently. This class is the join between the person and one of them.
Making the relationship its own class is what allows the several-to-several case without a compound key: two applicants can be attributed a share of the same rental income, and one applicant can hold six income records, using the same shape in both directions.
## In practice
Income writes one of these per record it returns, and the qualification layer under Income reads them to decide which figures may be counted.
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_income` | `income` | A person has income. Income is money that a person or organization earns or receives on a regular basis from various sources. |
| `has_person` | `person` | A member is also a person. |
---
# person
# person
An individual, and the class the largest number of others point at.
A person is an individual member of the human race.
## Why it matters
Everything in a transaction attaches to a person: the borrower and coborrower, the loan officer, the seller, the notary, the agent. The class carries only what is true of the individual — name, demographics, identification, citizenship — and everything role-shaped hangs off it as a relationship instead.
That split is why the class is small relative to how much points at it. A person is not a borrower; a person has a finance relation whose role is borrower, and the same person can hold several such relations at once.
## In practice
Identity across states is a stable global identifier named for the class, while every state of the record carries its own database-generated identifier. A correction to a name is a new record grouped with the old one rather than an overwrite, so the history of what was believed and when is a query rather than an audit log.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `birth_date` | `date` | A birth date is the date on which a person was born. It typically includes the day, month, and year of an individual's birth and is used to determine their age. |
| `city_name` | `string` | City name refers to the name of the city in which the address is located. |
| `country_name` | `string` | Country name refers to the country where a person resides. |
| `email_address` | `string` | An email address is a unique identifier used to send and receive electronic messages over the internet. It typically consists of two parts: a username and a domain name, separated by the '@' symbol. |
| `first_name` | `string` | A person's first name is the name that they are given at birth or during infancy, and it is typically used to identify them in a personal or informal context. |
| `first_time_home_owner` | `boolean` | First time home owner refers a person who is purchasing a house and taking out a mortgage for the first time. |
| `full_address_txt` | `string` | Full address text refers to the physical location where property is located. |
| `has_saved_search` | `saved_search` | Links a person to a saved search instance, indicating that the person has saved this particular search. |
| `home_phone_number` | `string` | A home phone number is a telephone number that is associated with a residential address, typically used for personal or family communication purposes. It is a phone number that is linked to a landline or a Voice over Internet Protocol (VoIP) service that is connected to a physical address. |
| `last_name` | `string` | A person's last name, also known as surname or family name, is typically the name that is shared by all members of their immediate family. |
| `mailing_address` | `string` | A mailing address is the physical location where mail is sent to a person or organization. It typically includes the recipient's name, street address, city, state or province, postal code and country. |
| `owned_environments` | `environment` | Owned environment refers to a computing environment that is fully controlled by a particular person or organization. In an owned environment, the person or organization has complete control over the configuration, management, and security of the computing resources. This allows them to customize the environment to their specific needs and requirements, and to ensure that it is optimized for the application or service they are running. |
| `person_identifier` | `string` | A person identifier is a unique code or number assigned to an individual for identification purposes. It is often used in various administrative and legal systems to ensure accuracy and consistency in record-keeping and data management. |
| `phone_number` | `string` | A phone number is a unique sequence of digits assigned to a specific telephone line or mobile device that allows it to be reached by a caller. It is typically comprised of a country code, area code, and a specific number assigned to the device. |
| `postal_code` | `string` | A postal code, also known as a ZIP code (in the United States) or postcode (in many other countries), is a numerical code used by postal services to identify specific geographic areas for efficient mail sorting and delivery. |
| `ssn` | `string` | A Social Security number (SSN) is a unique nine-digit identification number assigned to individuals in the United States by the Social Security Administration (SSA). The SSN is used primarily for tracking individuals for Social Security and tax purposes, but it is also used for a variety of other purposes, such as credit reporting, employment verification, and financial transactions. |
| `state_code` | `string` | State code is a code that represents the state in which the address is located. |
| `state_name` | `string` | State name refers to the name of the state in which the address is located. |
| `us_citizenship_status` | `enumeration` | Citizenship status refers to an individual's legal status as a citizen or non-citizen of a country. In the United States, citizenship status is determined by birthright, naturalization, or other legal means. `USCitizen``USCitizenAbroad``PermResidentAlien``NonPermResidentAlien``ForeignNational` |
| `veteran_status` | `boolean` | Veteran status refers to an individual's status as a former member of the armed forces. In the United States, a person is considered a veteran if they have served in the active military, naval, or air service and were discharged or released from that service under conditions other than dishonorable. |
| `work_phone_number` | `string` | A work phone number is a telephone number that is associated with an individual's place of employment. It is typically used for business purposes, such as to contact colleagues, clients, or customers. |
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `earns` | `income` | A person has income. Income is information about the money that a person or organization earns or receives on a regular basis from various sources. For a person, income typically comes from wages or salaries earned from employment, as well as from investments, rental properties, or other sources of passive income. Income for organizations can come from sales of products or services, investments, grants, donations, or other sources. |
| `has_credit` | `credit` | A person can have credit. Credit is a person's ability to borrow money or obtain goods or services with the understanding that they will pay for them later. Credit is typically measured by a credit score, which is a numerical rating that reflects a person's creditworthiness based on their credit history, income, debt-to-income ratio, and other factors. |
## Referenced by
- `employment`
- `finance_relation`
- `person_credit`
- `person_income`
---
# pricing_schema
# pricing_schema
Pricing schema refers to the method used by lenders to determine the interest rate and other fees associated with a mortgage loan.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `apr` | `decimal` | Annual Percentage Rate (APR) represents the total cost of borrowing money over the life of the loan and is expressed as a percentage. The APR includes not only the interest rate, but also any points, origination fees, closing costs, and other charges associated with the loan. In general, the APR will be higher than the interest rate, since it includes the additional fees and charges associated with the loan. |
| `closing_cost` | `decimal` | Pricing schema closing costs define how much money a borrower will need to close on a mortgage. Closing costs refer to the fees and expenses that a borrower must pay at the closing of a mortgage loan. |
| `discount` | `decimal` | A pricing schema discount is a reduction in the interest rate offered on a mortgage loan, typically in exchange for paying an upfront fee known as a discount point. Discount points are a form of prepaid interest that a borrower can pay at closing to reduce the interest rate on the mortgage loan. One discount point typically equals 1% of the loan amount and can reduce the interest rate by 0.125% to 0.25%, although the exact reduction may vary depending on the lender and loan program. |
| `first_year_monthly_payment` | `decimal` | First year monthly payment refers to the amount of money that a borrower must pay each month during the first year of their mortgage loan. The first-year monthly payment will depend on several factors, including the loan amount, interest rate, term, and any upfront costs, such as closing costs or prepaid expenses for property taxes and insurance. In some cases, lenders may offer a lower introductory interest rate or other incentives during the first year of the loan, which can result in a lower first-year monthly payment. |
| `monthly_insurance` | `decimal` | Monthly insurance refers to the cost of mortgage insurance, which is an insurance policy that protects the lender in case the borrower defaults on the loan. Mortgage insurance is typically required when the borrower has a down payment of less than 20% of the home's purchase price. The monthly mortgage insurance premium is typically added to the borrower's monthly mortgage payment. |
| `piti` | `decimal` | PITI stands for Principal, Interest, Taxes, and Insurance. PITI is a commonly used pricing schema in the mortgage industry to calculate the total monthly payment that a borrower will need to make on a mortgage loan. |
| `price` | `decimal` | Price refers to the total cost of borrowing money for a mortgage loan. The price includes not only the interest rate charged on the loan but also any fees and charges associated with the loan, such as points, origination fees, and closing costs. |
| `pricing_schema_identifier` | `string` | A pricing schema identifier is a unique identification number assigned to a mortgage pricing schema. |
| `principal_and_interest` | `decimal` | A mortgage pricing schema that separates the mortgage payment into principal and interest is a way of structuring the payment so that a portion of the payment goes toward paying off the principal balance of the loan, and another portion goes toward paying the interest charged on the outstanding balance. In this schema, the principal is the original amount borrowed, and the interest is the fee charged by the lender for the use of the borrowed money. The mortgage payment is typically structured to pay off both the principal and interest over the life of the loan, with a greater proportion of the payment going towards interest at the beginning of the loan term and a greater proportion going towards principal as the loan matures. |
| `rate` | `decimal` | Rate refers to the interest rate at which the borrower will be charged interest on the outstanding balance of the loan. The interest rate does not take into account any fees or charges associated with the loan. In general, the interest rate will be lower than the annual percentage rate (APR) will be higher than the interest rate, since it does not include the additional fees and charges associated with the loan. |
| `rebate` | `decimal` | Rebate refers to a discount or credit that a lender offers to a borrower as an incentive to select a particular mortgage pricing option. It allows lenders to offer borrowers lower interest rates or fees in exchange for selecting a particular mortgage pricing structure. |
| `second_year_monthly_payment` | `decimal` | Second year monthly payment refers to the amount of money that a borrower must pay each month starting from the second year of the mortgage loan term. For fixed-rate mortgages, the monthly payment for a mortgage loan will remain the same throughout the entire term of the loan. However, some adjustable-rate mortgages (ARMs) have an initial fixed-rate period, after which the interest rate and monthly payment can change based on market conditions. Therefore, if a mortgage loan has an adjustable interest rate with an initial fixed-rate period of one year, the second-year monthly payment will depend on the current market interest rate at the end of the initial fixed period. The monthly payment may increase or decrease based on the interest rate at that time, which can result in a higher or lower payment amount for the borrower. |
| `third_year_monthly_payment` | `decimal` | Third year monthly payment refers to the amount a money that a borrower must pay each month to repay a mortgage loan during the third year of the loan term. The third year monthly payment can be calculated based on the loan amount, interest rate, and amortization term of the mortgage loan. However, the interest rate and other terms of the loan may change over time, particularly if the loan has an adjustable-rate mortgage (ARM) feature. In this case, the third year monthly payment would depend on the interest rate at that time, which may be higher or lower than the initial rate. |
| `total_monthly_payment` | `decimal` | Total monthly payment refers to the amount of money a borrower must pay each month to repay a mortgage loan, including principal and interest, as well as any escrow payments for property taxes and homeowners insurance. |
## Referenced by
- `mortgage_application`
---
# property_tax
# property_tax
The link between a property and a tax record.
Property tax describes properties related to taxes levied on the value of real estate or other types of property, such as land, buildings, and homes.
## Why it matters
Two references and nothing else. A property has tax assessed against it, the tax record carries the amounts and the periods, and this class joins them.
Keeping the tax record separate from the property is what allows a history. A parcel has a new assessment every year and several tax records at once for different authorities, and either case would break a set of tax fields on the property itself.
## In practice
Tax writes these against the parcel record, and the escrow calculation on a loan reads them.
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_property` | `property` | Property is a piece of land and any structures or improvements that are permanently attached to it. In the context of property tax, a property can have a tax levied against it. The tax is usually assessed and collected by local governments, such as cities or counties, and is used to fund local services such as schools, police and fire departments, road maintenance, and other community services. |
| `has_tax` | `tax` | A person who owns a financial asset may have to pay taxes on the asset. Taxes are fees levied by federal, state, and local governments on income, goods and services, and property, among other things. In the context of finance, tax is considered a financial debt. |
---
# property
# property
A parcel of land and what stands on it, as the mortgage model records it.
Property is a piece of land and any structures or improvements that are permanently attached to it.
## Why it matters
An identifier, a type, a purchase price, a lien type, the address as flat fields, and a reference to the tax levied against it.
This is the loan file's view of a property, and it is deliberately thinner than the collateral model. The question it answers is which property secures this loan and on what terms — not what the property is made of.
## In practice
The structural description lives in the property model under Data, which carries the parcel, the structure, the lot and the rest at assessor-record depth. The two are joined by address and parcel identity rather than merged, because one is a term of a loan and the other is a description of a place.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `city_name` | `string` | City name refers to the name of the city in which the address is located. |
| `county_name` | `string` | A property county name refers to the name of the county in which a property is located. In the United States, counties are geographic and political subdivisions of states, typically governed by a county government. Each county is identified by a unique name and is responsible for providing certain public services to residents, such as law enforcement, public schools, and infrastructure maintenance. |
| `full_address_txt` | `string` | Full address text refers to the physical location where property is located. |
| `lien_type` | `enumeration` | A property lien is a legal claim against a property that gives a creditor the right to take possession of the property if the borrower fails to repay a debt. There are several lien types, such as mortgage, tax and judgment.Typically a lien gives its holder the right to seize property or money from the borrower if the borrower does not fulfill the terms of a contract. `Mortgage``Tax``Mechanics``Judgement``Other` |
| `postal_code` | `string` | A postal code, also known as a ZIP code (in the United States) or postcode (in many other countries), is a numerical code used by postal services to identify specific geographic areas for efficient mail sorting and delivery. |
| `property_identifier` | `string` | A property identifier is a unique code or number assigned to a specific real estate property by a government agency or other organization. Property identifiers are used to identify and track individual properties for various purposes, such as taxation, land use planning, and real estate transactions. |
| `property_type` | `enumeration` | Property type refers to the classification of a real estate property based on its characteristics, usage, and zoning designation. Property types can include residential, commercial, industrial, agricultural, and mixed-use properties. `2_units``3_units``4_units``single_family``condo``duplex``manufactured_home``manufactured_double_wide``modular``pud``timeshare``manufactured_single_wide``coop``non_warrantable_condo``townhouse``detached_condo` |
| `purchase_price_amount` | `decimal` | The purchase price is the amount of money that is paid to purchase a real estate property. This price includes the cost of the land and any buildings or other improvements on the property. The purchase price may also include other costs, such as closing costs, title insurance, and other fees associated with the transaction. |
| `state_code` | `string` | State code is a code that represents the state in which the address is located. |
| `state_name` | `string` | State name refers to the name of the state in which the address is located. |
| `street_name` | `string` | A street name is the name of a street on which an address is located. |
| `unit` | `enumeration` | A property unit is a self-contained and separately identifiable portion of a larger property or building that is designed to be used or occupied by a tenant or owner. Properties are typically single-unit and contain only a single homes or storefront, or multi-unit and contain multiple homes or storefronts. `1``2``3``4` |
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_tax` | `tax` | A person who owns a financial asset may have to pay taxes on the asset. Taxes are fees levied by federal, state, and local governments on income, goods and services, and property, among other things. In the context of finance, tax is considered a financial debt. |
## Referenced by
- `finance_relation`
- `property_tax`
---
# tax
# tax
A tax levied by an authority, for a period, with the payment against it and whether it is escrowed.
Taxes are fees levied by federal, state, and local governments on income, goods and services, and property, among other things.
## Why it matters
A tax record names the authority, the account held with it, the period it covers, the service provider that sourced it, and the payment made against it, plus an indicator for whether it is escrowed.
The period is what makes the record a history rather than a balance. A parcel carries a new assessment each cycle and can owe several authorities at once, so the class is deliberately one levy for one period rather than a current-tax field on the property.
## In practice
The escrow indicator is the field a servicing calculation reads first: an escrowed tax is collected monthly and paid by the servicer, and an unescrowed one is the borrower's to pay directly.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `authority_account_identifier` | `string` | Authority account identifier is a tax identifier issued to individuals and organizations to track tax obligations and payments they make to a tax authority. |
| `authority_name` | `string` | Authority name refers to the name of an organization authorized to collect taxes from individuals and other organizations. |
| `description` | `decimal` | A company description is a brief summary or overview of a business. It typically includes information such as the company's industry, size, products or services offered, target market, and mission statement. |
| `escrowed_indicator` | `boolean` | The escrowed indicator specifies whether a mortgage servicer takes a portion of the borrower's monthly mortgage payment and holds it in an escrow account until tax payments are due. |
| `period_end_date` | `date` | Period end date is the last day in a time period during which tax liability is accruing. |
| `period_start_date` | `date` | Period start date is the first day in a time period during which tax liability is accruing. |
| `service_provider_identifier` | `string` | A service provider identifier is a unique identifier issued to a company or individual who offers professional tax-related services to individuals, businesses, and other organizations. |
| `service_provider_name` | `string` | Service provider name is the name of a company or individual who offers professional tax-related services to individuals, businesses, and other organizations. |
## Relationships
| Property | Points at | Definition |
| --- | --- | --- |
| `has_payment` | `payment` | A payment refers to the transfer of money, goods, or services from one party (the payer) to another party (the payee) in exchange for a product, service, or debt settlement. Payments can take various forms, including cash, checks, bank transfers, credit cards, electronic funds transfers, mobile payments, and digital currencies. |
## Referenced by
- `finance_relation`
- `property`
- `property_tax`
---
# Property model
# Property model
The property class dictionary: the physical asset, the parcel it sits on, and the public record behind both.
One parcel, decomposed into the classes a valuation needs: the structure, its layout and utilities, the lot, the deed and sales history, the tax position, and the surrounding jurisdiction records.
The published classes are the subgraph the declared data groups reach. The full graph carries more, and a class no data group reaches has no way to be requested.
## How it is governed
Group membership is derived from the relationships the data groups declare rather than from a hand-maintained list, so a class enters or leaves the published set when the groups change and not when someone remembers.
Enumerations are the failure surface, and the rule is that an unmapped source value is an error rather than a default. An extraction script that meets a value it cannot map throws, naming the class and property; it does not assign a plausible substitute. That is the single rule that keeps a wrong value out of the dataset at jurisdiction scale.
## How it works
The decomposition is partitioned so a source can update part of a record without rewriting it. A permit filing changes the improvement history and nothing else; a deed recording changes ownership and sales history and nothing else. Grouping by what changes together is what makes partial update safe.
Every value can name where it came from. A source class carries the contributor and the specific attribute it supplied, alongside the vendor's own identifier and the time of the call, so the graph answers which source produced a given fact rather than only what the fact is.
Records are accepted on agreement rather than on arrival. Independent re-derivation of the same parcel must agree before a value is taken, and change is detected by content hash against the source rather than by re-reading on a schedule.
## Classes
Grouped by the question each answers about a property.
### What is this house, physically?
- `property`
- `parcel`
- `structure`
- `lot`
- `layout`
- `appliance`
- `utility`
- `geometry`
- `property_ranking_overall`
- `environment_characteristics`
- `flood_storm_information`
- `safety_security`
- `school`
- `transportation_access`
### What changed since it was built?
- `property_improvement`
- `inspection`
- `file`
### What are the comparables, really?
- `sales_history`
- `deed`
### Who owns it, and what does that imply?
- `person`
- `address`
- `unnormalized_address`
- `property_seed`
### Will this close cleanly?
- `loan`
- `tax`
- `tax_authority`
- `tax_exemption`
- `tax_jurisdiction`
- `homeowners_association`
- `hoa_policy`
## The classes carrying the most
| Class | Properties | Referenced by |
| --- | --- | --- |
| `structure` | 59 | 0 |
| `layout` | 49 | 0 |
| `utility` | 46 | 0 |
| `tax` | 26 | 0 |
| `address` | 24 | 0 |
| `lot` | 21 | 0 |
| `environment_characteristics` | 21 | 0 |
| `property` | 19 | 0 |
Derived from: property graph, restricted to the classes its data groups reach (repository source)
---
# address
# address
A physical or mailing address, parsed into components with postal and geographic identifiers.
Represents a physical or mailing address with comprehensive location details including street information, postal codes and geographic identifiers.
The question it answers
## Who owns it, and what does that imply?
A deed names its parties as strings. Resolving those strings to a person and a mailing address is what separates an owner-occupant from an investor, and what links one owner to the rest of a portfolio.
Other classes answering this question
## Why it matters
The parsed address is the join key of last resort. Where a parcel identifier cannot be matched across two sources, a normalised address is what connects them, so the parsing has to be consistent rather than merely correct.
## In practice
The class holds components rather than a line of text: street number, name, suffix, directionals, unit, locality, state and postal code, each addressable. Directional prefixes and suffixes are separate fields because a county that writes them differently is otherwise an unmatched record.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `city_name` | `string | null` | City name refers to the name of the city in which the address is located. Must be in all capital letters. |
| `country_code` | `string | null` | Country code is a code that represents the country in which the address is located. |
| `county_name` | `string` | County name refers to the name of the county in which the address is located. `Dallas``Miami Dade``Broward``Palm Beach``Lee``Hillsborough``Orange``Pinellas``Polk``Duval``Brevard``Pasco``Volusia``Sarasota``Collier``Marion``Manatee``Charlotte``Lake``Osceola``St. Lucie``Seminole``Escambia``St. Johns``Citrus``Bay``Santa Rosa``Hernando``Okaloosa``Highlands``Leon``Alachua``Clay``Sumter``Putnam``Martin``Indian River``Walton``Monroe``Flagler``Nassau``Levy``Washington``Jackson``Suwannee``Columbia``Hendry``Okeechobee``Gadsden``Wakulla``DeSoto``Gulf``Taylor``Franklin``Dixie``Madison``Bradford``Hardee``Gilchrist``Holmes``Calhoun``Hamilton``Baker``Jefferson``Glades``Lafayette``Union``Liberty``Fort Bend``Collin``Allegheny``Hunt``Wood``Burnet``San Patricio``Wise``Nacogdoches``Waller``Cherokee``Navarro``Medina``Alameda``Alpine``Amador``Butte``Calaveras``Colusa``Contra Costa``Del Norte``El Dorado``Fresno``Glenn``Humboldt``Imperial``Inyo``Kern``Kings``Lake``Lassen``Los Angeles``Madera``Marin``Mariposa``Mendocino``Merced``Modoc``Mono``Monterey``Napa``Nevada``Orange``Placer``Plumas``Riverside``Sacramento``San Benito``San Bernardino``San Diego``San Francisco``San Joaquin``San Luis Obispo``San Mateo``Santa Barbara``Santa Clara``Santa Cruz``Shasta``Sierra``Siskiyou``Solano``Sonoma``Stanislaus``Sutter``Tehama``Trinity``Tulare``Tuolumne``Ventura``Yolo``Yuba``Ellis` |
| `latitude` | `number | null` | Latitude is a coordinate that specifies the north-south position of a point on the Earth's surface. It is an angular measurement, usually expressed in degrees, with values ranging from -90° at the South Pole to +90° at the North Pole. |
| `longitude` | `number | null` | Longitude is a coordinate that specifies the east-west position of a point on the Earth's surface. It is an angular measurement, usually expressed in degrees, with values ranging from -180° to +180°. |
| `municipality_name` | `string | null` | he incorporated city, town, or village in which the property is located, responsible for providing local government services and regulations. |
| `plus_four_postal_code` | `string | null` | A postal code plus four, also known as a ZIP code plus four (in the United States) is a numerical extension to a postal code. |
| `postal_code` | `string | null` | A postal code, also known as a ZIP code (in the United States) or postcode (in many other countries), is a numerical code used by postal services to identify specific geographic areas for efficient mail sorting and delivery. |
| `state_code` | `string | null` | State code is a code that represents the state in which the address is located. |
| `street_name` | `string | null` | A street name that doesn't contain directional abbreviations |
| `street_post_directional_text` | `string | null` | Street post directional text refers to the directional indicator or suffix added to a street name to provide additional information about the direction or orientation of the street segment. It helps to clarify the position of a particular street in relation to other streets or landmarks in a given area. `N``S``E``W``NE``NW``SE``SW` |
| `street_pre_directional_text` | `string | null` | Street pre directional text refers to the directional indicator or prefix added to a street name to provide additional information about the direction or orientation of the street segment. It helps to clarify the position of a particular street in relation to other streets or landmarks in a given area. `N``S``E``W``NE``NW``SE``SW` |
| `street_number` | `string | null` | Street number refers to the numerical part of a street address that indicates the specific location or position of a building or property along a street. |
| `street_suffix_type` | `string | null` | `Rds``Blvd``Lk``Pike``Ky``Vw``Curv``Psge``Ldg``Mt``Un``Mdw``Via``Cor``Kys``Vl``Pr``Cv``Isle``Lgt``Hbr``Btm``Hl``Mews``Hls``Pnes``Lgts``Strm``Hwy``Trwy``Skwy``Is``Est``Vws``Ave``Exts``Cvs``Row``Rte``Fall``Gtwy``Wls``Clb``Frk``Cpe``Fwy``Knls``Rdg``Jct``Rst``Spgs``Cir``Crst``Expy``Smt``Trfy``Cors``Land``Uns``Jcts``Ways``Trl``Way``Trlr``Aly``Spg``Pkwy``Cmn``Dr``Grns``Oval``Cirs``Pt``Shls``Vly``Hts``Clf``Flt``Mall``Frds``Cyn``Lndg``Mdws``Rd``Xrds``Ter``Prt``Radl``Grvs``Rdgs``Inlt``Trak``Byu``Vlgs``Ctr``Ml``Cts``Arc``Bnd``Riv``Flds``Mtwy``Msn``Shrs``Rue``Crse``Cres``Anx``Drs``Sts``Holw``Vlg``Prts``Sta``Fld``Xrd``Wall``Tpke``Ft``Bg``Knl``Plz``St``Cswy``Bgs``Rnch``Frks``Ln``Mtn``Ctrs``Orch``Iss``Brks``Br``Fls``Trce``Park``Gdns``Rpds``Shl``Lf``Rpd``Lcks``Gln``Pl``Path``Vis``Lks``Run``Frg``Brg``Sqs``Xing``Pln``Glns``Blfs``Plns``Dl``Clfs``Ext``Pass``Gdn``Brk``Grn``Mnr``Cp``Pne``Spur``Opas``Upas``Tunl``Sq``Lck``Ests``Shr``Dm``Mls``Wl``Mnrs``Stra``Frgs``Frst``Flts``Ct``Mtns``Frd``Nck``Ramp``Vlys``Pts``Bch``Loop``Byp``Cmns``Fry``Walk``Hbrs``Dv``Hvn``Blf``Grv``Crk` |
| `unit_identifier` | `string | null` | A unit identifier is a reference to the specific unit, suite, apartment, or other secondary identifier associated with an address. It is used to differentiate individual units within a larger building or complex. |
| `route_number` | `string | null` | A route number is a unique identifier assigned to a specific transportation route, such as a road, highway, or public transit line. It is used to distinguish one route from another and is often displayed on signs or maps. |
| `township` | `string | null` | A township is a 6-mile by 6-mile square of land, covering 36 square miles. Townships are numbered north or south from a designated baseline. In this case, Township 45 refers to the 45th tier of townships from the baseline. |
| `range` | `string | null` | A range describes the east-west position of a township relative to a principal meridian. Range 24E means the township is located 24 tiers east of the principal meridian |
| `section` | `string | null` | Each township is divided into 36 sections, with each section being 1 square mile (640 acres). Section 03 refers to the third section within its township |
| `block` | `string | null` | A block is a further subdivision within a plat (a recorded land division), often used in urban or planned developments. Block 0000G refers to a specific block within that recorded subdivision |
| `lot` | `string | null` | A specific parcel or unit of land within a subdivision or plat, identified by a unique lot number or code assigned during the subdivision platting process. |
| `unnormalized_address` | `string | null` | The original, unprocessed address as it appears in source data, preserving the raw format and any inconsistencies. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# appliance
# appliance
Appliances present at the property, as recorded in the source.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Appliances are a minor line in a valuation and a real one in a condition assessment: a property recorded with no appliances is either a shell or a record gap, and the two need different handling.
Two fields carry the content — the appliance type and its visible finish — and both are closed enumerations rather than free text, so an inventory aggregates across properties without a normalisation pass. The finish is what separates a recent kitchen from an original one where no permit exists to date it.
The source dictionary carries no definition for this class.
## In practice
Rows come from photograph metadata rather than from an assessor file, which is why an empty set means unobserved rather than absent. A property with no interior photographs on record carries no appliance rows at all.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `appliance_type` | `string | null` | The appliance type observed in the space. `Refrigerator``Freezer``Microwave``Oven``Stove``Dishwasher``Washing Machine``Dryer``Range Hood``Wine Cooler``Trash Compactor``Water Heater``Cooktop``Double Oven``Built-In Coffee Maker``Wall Oven``Mini Fridge``Ice Maker``Garbage Disposal``Smart Display``Toaster Oven` |
| `finish` | `string | null` | The visible finish of the appliance. `Stainless Steel``Black``White``Glass``Matte Black``Matte White``Custom Panel``Chrome``Copper``Brushed Nickel` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# deed
# deed
A recorded instrument transferring ownership: its type, its recording data, the parties, and the consideration stated on it.
Represents a legal deed document that transfers ownership of real property from one party to another.
The question it answers
## What are the comparables, really?
A recorded deed is the legal source of truth for a transfer: instrument type, consideration, parties, and date. That is what separates an arm's-length sale from a quitclaim between relatives, an estate transfer, a foreclosure, or an investor flip. A comp set that silently includes non-arm's-length transfers is biased before the model sees it.
Other classes answering this question
## Why it matters
The instrument type is the field that does the work, and it is the one an aggregated feed most often loses. Warranty deed, quitclaim, trustee's deed, personal representative's deed and certificate of title are different legal events with different implications for what the stated consideration means.
Consideration on a quitclaim is frequently nominal and is not a price.
## In practice
Recording data — the instrument number, book and page, and the clerk's file reference — is carried because it is how the document itself is retrieved. A transfer without its recording reference cannot be checked against the source, and this class is the one most worth being able to check.
A single deed can convey several parcels, which is why the transfer record is `sales_history` and this class is the document.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `deed_type` | `string` | The type of deed document used to transfer property ownership. `Warranty Deed``Special Warranty Deed``Quitclaim Deed``Grant Deed``Bargain and Sale Deed``Lady Bird Deed``Transfer on Death Deed``Sheriff's Deed``Tax Deed``Trustee's Deed``Personal Representative Deed``Correction Deed``Deed in Lieu of Foreclosure``Life Estate Deed``Joint Tenancy Deed``Tenancy in Common Deed``Community Property Deed``Gift Deed``Interspousal Transfer Deed``Wild Deed``Special Master’s Deed``Court Order Deed``Contract for Deed``Quiet Title Deed``Administrator's Deed``Guardian's Deed``Receiver's Deed``Right of Way Deed``Vacation of Plat Deed``Assignment of Contract``Release of Contract``Miscellaneous` |
| `book` | `string` | The book number where the deed is recorded in public records. |
| `page` | `string` | The page number within the book where the deed is recorded. |
| `volume` | `string` | The volume number associated with the deed recording. |
| `instrument_number` | `string` | The unique instrument number assigned to the deed document upon recording. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# environment_characteristics
# environment_characteristics
Environmental factors and natural-disaster exposure around the property.
Environmental factors, natural disaster risks, and surroundings that affect property desirability and safety.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Environmental exposure is priced by insurers before it is priced by buyers, so it reaches a valuation through carrying cost as much as through desirability.
## In practice
The class covers surroundings as well as hazards, which is deliberate: proximity to industrial use, noise and air quality are recorded facts about a location in some jurisdictions and are otherwise only visible from a site visit.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `fire_zone` | `string | null` | Wildfire risk zone or fire district designation indicating wildfire hazard level and emergency response district. |
| `wildfire_risk_level` | `string | null` | Standardized wildfire risk assessment based on vegetation, weather patterns, topography, and fire history. `VeryLow``Low``Moderate``High``VeryHigh``Extreme` |
| `air_quality_index` | `string | null` | EPA Air Quality Index category indicating typical air pollution levels for the area. `Good``Moderate``UnhealthyForSensitiveGroups``Unhealthy``VeryUnhealthy``Hazardous` |
| `air_quality_compliance` | `boolean` | Whether area is in attainment for all EPA ambient air quality standards. |
| `noise_level` | `string | null` | Ambient noise level in the area affecting quality of life and property desirability. `Quiet``Moderate``Busy``Loud` |
| `noise_sources` | `array` | Specific sources of noise in the area. |
| `light_pollution_level` | `string | null` | Light pollution level affecting night sky visibility and natural darkness. `Dark``Rural``Suburban``Urban` |
| `earthquake_zone` | `string | null` | Seismic zone designation or earthquake risk classification for the area. |
| `soil_stability` | `string | null` | Soil stability assessment considering factors like erosion, subsidence, and landslide risk. `Stable``Moderate``Unstable``HighRisk` |
| `environmental_hazards` | `array` | List of additional environmental hazards present in the area (e.g., 'Radon', 'Industrial Pollution', 'Mining Activity'). |
| `flood_risk_level` | `string | null` | Flood risk assessment based on FEMA flood zone data. `Minimal``Low``Moderate``High``Extreme` |
| `flood_zone_designation` | `string | null` | FEMA flood zone designation (e.g., 'Zone X', 'Zone AE'). |
| `flood_insurance_required` | `boolean` | Whether flood insurance is required for the property. |
| `wind_storm_risk` | `string | null` | Wind storm and hurricane risk assessment. `Minimal``Low``Moderate``High``Extreme` |
| `hurricane_engineering_compliance` | `boolean` | Whether building is engineered for hurricane winds per current code. |
| `radon_risk_level` | `string | null` | Radon gas exposure risk assessment. `Low``Moderate``High``Concern` |
| `radon_building_type_assessment` | `string | null` | Radon risk specific to building type (e.g., 'rarely an issue in low-rise wood frame condos'). |
| `environmental_surroundings` | `string | null` | Primary environmental setting surrounding the property. `CoastalBeach``Mountains``Desert``Forest``Urban``Suburban``Rural``Industrial` |
| `beach_proximity` | `object` | Details about nearby beach access if applicable. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# file
# file
Media and documents associated with a property: images, recorded documents, and their source references.
The file class is a comprehensive data structure that represents all media and documents associated with a specific property, including images, PDFs, and floor plans across multiple file formats (JPEG, PNG, PDF).
The question it answers
## What changed since it was built?
Two physically identical houses on the same street diverge by six figures if one had a gut renovation. Photographs show current condition but not cost basis, scope, or recency. A permit records all three, and a pulled but unfinalised permit is a leading indicator priced differently again. Permits are issued by municipalities rather than counties, which is an order of magnitude more integration surface than parcel data and the reason incumbent coverage is thin.
Other classes answering this question
## Why it matters
Documents are how a claim is verified. A deed record links to the recorded instrument; a permit links to the filing; a photograph is dated evidence of condition. The class carries the reference rather than the bytes, so the record stays small and the source stays authoritative.
## In practice
Each entry carries the source reference it was retrieved by, which for county clerk documents is a document number resolvable against the clerk's own index. That is what allows a document cited here to be re-fetched independently rather than taken on trust.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object | null` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `file_format` | `string | null` | The format or MIME type of the file. `jpeg``png``txt` |
| `name` | `string | null` | A human-friendly name for the media asset. |
| `original_url` | `string | null` | HTTP/HTTPS source URL of the media asset. |
| `document_type` | `string | null` | Semantic role or classification of the document. `Title``ConveyanceDeedQuitClaimDeed``ConveyanceDeedBargainAndSaleDeed``ConveyanceDeedWarrantyDeed``ConveyanceDeed``AssignmentAssignmentOfDeedOfTrust``AssignmentAssignmentOfMortgage``AssignmentAssignmentOfRents``Assignment``AssignmentAssignmentOfTrade``AssignmentBlanketAssignment``AssignmentCooperativeAssignmentOfProprietaryLease``AffidavitOfDeath``AbstractOfJudgment``AttorneyInFactAffidavit``ArticlesOfIncorporation``BuildingPermit``ComplianceInspectionReport``ConditionalCommitment``CounselingCertification``AirportNoisePollutionAgreement``BreachNotice``BrokerPriceOpinion``AmendatoryClause``AssuranceOfCompletion``Bid``BuildersCertificationBuilderCertificationOfPlansAndSpecifications``BuildersCertificationBuildersCertificate``BuildersCertificationPropertyInspection``BuildersCertificationTermiteTreatment``PropertyImage` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Santa Clara, California
How a new jurisdiction is brought online
---
# flood_storm_information
# flood_storm_information
Federal flood mapping for the property: zone classification, insurance requirement, community and panel identifiers, and evacuation designation.
FEMA flood and storm information data containing flood zone classifications, insurance requirements, and evacuation zone designations for property locations.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Flood zone determines whether insurance is mandatory, which is a monthly cost and, in some markets, a financeability question rather than a preference. Evacuation designation is a separate and locally-defined overlay that does not follow the flood map.
## In practice
The panel and version identifiers are carried alongside the zone because maps are revised, and a determination is only as good as the panel it was read from. A zone without the panel it came from cannot be re-checked.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `community_id` | `string | null` | The FEMA community identifier code for the jurisdiction where the property is located. |
| `panel_number` | `string | null` | The FEMA flood insurance rate map (FIRM) panel number that contains the property location. |
| `map_version` | `string | null` | The version identifier of the FEMA flood map panel. |
| `effective_date` | `string | null` | The date when the current flood map version became effective. Format: MM/DD/YYYY or YYYY-MM-DD. |
| `evacuation_zone` | `string | null` | The evacuation zone designation (e.g., A, B, C) assigned to the property location for emergency planning purposes. |
| `flood_zone` | `string | null` | The FEMA flood zone designation indicating the level of flood risk (e.g., AE, X, VE). |
| `flood_insurance_required` | `boolean` | Indicates whether flood insurance is required based on the flood zone designation and federal regulations. |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `fema_search_url` | `string | null` | The FEMA Map Service Center URL used to search and verify flood information for the specific property address. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# geometry
# geometry
Coordinate data for a property or parcel: point locations and polygon boundaries.
Represents geographical coordinate data including single points and polygonal boundaries for properties and parcels.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
The boundary is what makes spatial questions answerable — whether a parcel touches a flood zone, backs onto a commercial use, or falls inside a school attendance boundary. A point alone answers none of those.
## In practice
Both forms are carried because sources publish both, and a centroid derived from a polygon is not the same as a geocoded address point. Which one a record holds determines which spatial queries can be trusted against it.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `latitude` | `number | null` | Latitude coordinate of a single point location, ranging from -90° (South Pole) to +90° (North Pole). |
| `longitude` | `number | null` | Longitude coordinate of a single point location, ranging from -180° to +180°. |
| `polygon` | `array` | An array of coordinate points defining a closed polygon boundary. Requires at least 3 points to form a valid polygon. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# hoa_policy
# hoa_policy
The rules and restrictions an association applies to the properties it governs.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
Restrictions are what determine whether a property can be used the way a buyer intends — rental caps, occupancy limits, and architectural controls all bear on value and none of them is visible in the physical record.
Four fields split the rules by what they restrict: leasing, pets, vehicles, and everything else the association governs. Leasing is the one that changes an investment case outright — a minimum stay of six months and an owner-occupied-only rule are different assets at the same price.
The source dictionary carries no definition for this class.
## In practice
Each field is a closed enumeration rather than the association's own prose, so a covenant document that says the same thing three different ways resolves to one value. The fees and amenities the same association declares sit in `homeowners_association`; this class is the rules only.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `leasing_policy` | `string | null` | Summary of leasing rules and duration limits (e.g., minimum stay, frequency, HOA approval). `NoRental``ShortTermRental``LongTermRental``MinimumStay30Days``MinimumStay6Months``MinimumStay1Year``HOAApprovalRequired``OwnerOccupiedOnly``UnlimitedRental``SeasonalRentalOnly` |
| `pet_policy` | `string | null` | Information about pet allowances and restrictions (e.g., pet friendly, breed/size restrictions). `NoPets``PetFriendly``DogsOnly``CatsOnly``SmallPetsOnly``WeightRestriction25lbs``WeightRestriction50lbs``BreedRestrictions``MaxTwoPets``PetDeposit``PetFee``ServiceAnimalsOnly` |
| `vehicle_policy` | `string | null` | Rules around parking and vehicle types (e.g., no RVs, reserved parking). `NoRestrictions``NoRVs``NoTrailers``NoCommercialVehicles``NoBoats``ReservedParkingOnly``GuestParkingRestricted``MaxTwoVehicles``CoveredParkingRequired``NoStreetParking``PermitRequired` |
| `general_restrictions` | `string | null` | Other HOA or property-wide lifestyle rules (e.g., quiet hours, storage bans, dress code). `NoRestrictions``QuietHours``NoSmoking``NoStorage``DressCode``NoSatelliteDishes``NoExteriorModifications``NoPoolAccess``NoGym``AgeLimited55Plus``NoShortTermGuests``HOAApprovalRequired` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# homeowners_association
# homeowners_association
An association governing a property: its identity, its fees, and what those fees cover.
The HomeownersAssociation class represents comprehensive information about homeowners associations (HOAs) governing residential properties, including community governance, financial obligations, and available amenities.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
Association dues are a monthly cost that a payment calculation has to include and a lending question in their own right — a project with inadequate reserves or high investor concentration can be unfinanceable regardless of the borrower.
## In practice
The association is separate from its policy because one association governs many properties under one set of rules, and recording the rules against every parcel would multiply the same facts.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `homeowners_association_name` | `string | null` | Name of the homeowners association (e.g., Jupiter Shores HOA). |
| `homeowners_association_type` | `string | null` | Refers to the type of Homeowners association (HOA). `Mandatory``Voluntary``Condominium``Hybrid` |
| `homeowners_association_amount` | `decimal` | Amount of HOA fees |
| `homeowners_association_year` | `integer | null` | year of for the HOA year |
| `homeowners_association_fee_frequency` | `string | null` | How often the HOA fee is charged. `Monthly``Quarterly``Annually``Bi-Annually``One-Time` |
| `amenities` | `string | null` | List of common amenities offered (e.g., pool, clubhouse, gym, golf course). `pool``clubhouse``gym``golf_course``tennis_court``playground``dog_park``spa``sauna``business_center``game_room``bbq_area``marina``bike_trails``walking_paths``rooftop_deck``community_kitchen``co_working_space``package_lockers` |
| `security_features` | `string | null` | Standard security infrastructure or services (e.g., 24/7 guard, gated entry, surveillance cameras). `24_7_guard``gated_entry``surveillance_cameras``keycard_access``security_patrols``doorman``intercom_system``secure_parking``fenced_perimeter``alarm_system``smart_locks` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# inspection
# inspection
An inspection record: the scheduled and completed dates, the outcome, and the permit it belongs to.
Represents a building or property inspection record, including scheduled dates, completion status, and associated permit information.
The question it answers
## What changed since it was built?
Two physically identical houses on the same street diverge by six figures if one had a gut renovation. Photographs show current condition but not cost basis, scope, or recency. A permit records all three, and a pulled but unfinalised permit is a leading indicator priced differently again. Permits are issued by municipalities rather than counties, which is an order of magnitude more integration surface than parcel data and the reason incumbent coverage is thin.
Other classes answering this question
## Why it matters
The inspection is what closes a permit. A permit with no final inspection is open work, which is a different valuation position from finished work — and the distinction is only visible if the inspection record is kept alongside the permit rather than folded into it.
## In practice
Inspection records come from the same municipal sources as permits and arrive on the same schedule, which is why they are extracted together and why their coverage matches.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `inspection_number` | `string` | Unique identifier for the inspection. |
| `inspection_status` | `string` | Current status of the inspection indicating whether it has been completed and the outcome. `Passed``Failed``Pending``Scheduled``Cancelled``In Progress` |
| `scheduled_date` | `string` | The date when the inspection is scheduled to occur. |
| `requested_date` | `string` | The date when the inspection was requested. |
| `completed_date` | `string` | The date when the inspection was completed. |
| `completed_time` | `string` | The time when the inspection was completed in ISO 8601 time format (HH:MM:SS or HH:MM:SS.sss). |
| `permit_number` | `string` | The permit number associated with this inspection, identifying the construction or renovation permit being inspected. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Santa Clara, California
How a new jurisdiction is brought online
---
# layout
# layout
Rooms and spaces within a property, one record per space, with the physical characteristics of each.
The Layout class provides comprehensive documentation of individual rooms and spaces within a property, capturing detailed physical characteristics, design elements, and condition assessments.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Bedroom and bathroom counts are the headline, but the reason to decompose by space is that the counts alone are ambiguous. A finished basement bedroom, a converted garage and an addition are all bedrooms in a count and are not the same thing in a price.
## In practice
Each space carries its own dimensions, finish and condition, so a valuation can distinguish gross living area from total area under roof. The distinction matters because assessors and listings measure them differently, and a comparison that mixes the two is comparing different quantities.
The extraction is multi-building aware: a parcel with a main house and a detached accessory unit produces spaces for both rather than merging them.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `building_number` | `integer | null` | The building number identifying which building the room or space is located in (useful for multi-building properties or complexes). |
| `total_area_sq_ft` | `integer | null` | Total enclosed building area in square feet, including all finished and unfinished spaces. |
| `built_year` | `integer | null` | The year in which the layout built. |
| `adjustable_area_sq_ft` | `integer | null` | Adjustable area in square feet used for planning or reconfiguration (e.g., flex or convertible spaces). |
| `livable_area_sq_ft` | `integer | null` | Heated living area in square feet (habitable space excluding garages, porches, and unfinished areas). |
| `heated_area_sq_ft` | `integer | null` | Heated area (served by permanent heating) in square feet. Typically overlaps living area under air. |
| `area_under_air_sq_ft` | `integer | null` | Air-conditioned area under air (A/C) in square feet. |
| `story_type` | `string | null` | Structural story classification if applicable `Full``Half Story``Three-Quarter Story` |
| `space_type` | `string | null` | The function or designation of the room. `Building``Living Room``Family Room``Great Room``Dining Room``Office Room``Conference Room``Class Room``Plant Floor``Kitchen``Breakfast Nook``Pantry``Primary Bedroom``Secondary Bedroom``Guest Bedroom``Children’s Bedroom``Nursery``Full Bathroom``Three-Quarter Bathroom``Half Bathroom / Powder Room``En-Suite Bathroom``Jack-and-Jill Bathroom``Primary Bathroom``Laundry Room``Mudroom``Closet``Bedroom``Walk-in Closet``Mechanical Room``Storage Room``Server/IT Closet``Home Office``Library``Den``Study``Media Room / Home Theater``Game Room``Home Gym``Music Room``Craft Room / Hobby Room``Prayer Room / Meditation Room``Safe Room / Panic Room``Wine Cellar``Bar Area``Greenhouse``Attached Garage``Detached Garage``Carport``Workshop``Storage Loft``Porch``Screened Porch``Sunroom``Deck``Patio``Pergola``Balcony``Terrace``Gazebo``Pool House``Outdoor Kitchen``Lobby / Entry Hall``Common Room``Utility Closet``Elevator Lobby``Mail Room``Janitor’s Closet``Pool Area``Indoor Pool``Outdoor Pool``Hot Tub / Spa Area``Shed``Lanai``Open Porch``Enclosed Porch``Attic``Enclosed Cabana``Carport``Attached Carport``Detached Carport``Detached Utility Closet``Jacuzzi``Courtyard``Open Courtyard``Screen Porch (1-Story)``Screen Enclosure (2-Story)``Screen Enclosure (3-Story)``Screen Enclosure (Custom)``Lower Garage``Lower Screened Porch``Screened Porch``Stoop``First Floor``Second Floor``Third Floor``Fourth Floor``Floor``Basement``Sub-Basement``Living Area``Barn` |
| `space_index` | `integer` | An index number representing the order of each space type in the property layout. |
| `space_type_index` | `string` | An index number representing the order of each space type and index in the property layout |
| `flooring_material_type` | `string | null` | Refers to the type of material used for a floor. `Manufactured``EngineeredWood``Terazzo``Brick``Wood``CinderBlock``Concrete``Shingle``Composition``Linoleum``Stone``CeramicTile``Block``WoodSiding``ImpactGlass``Carpet``Marble``Vinyl``Tile``PouredConcrete``Metal``Glass``Laminate` |
| `size_square_feet` | `number | null` | Room area in square feet. |
| `floor_level` | `string | null` | The floor level the room is on, useful for multi-story properties. `1st Floor``2nd Floor``3rd Floor``4th Floor` |
| `has_windows` | `boolean | null` | Whether the room has windows or not (relevant for egress and lighting). |
| `window_design_type` | `string | null` | Refers to the window design. `Skylights``Transom``Egress``Garden``Awning``DoubleHung``Jalousie``SingleHung``Sliding``Bay``Bow``Greenhouse``Picture``Casement` |
| `window_material_type` | `string | null` | Refers to the type of material a window is made from. `Manufactured``EngineeredWood``Terazzo``Brick``Wood``CinderBlock``Concrete``Shingle``Composition``Linoleum``Stone``CeramicTile``Block``WoodSiding``ImpactGlass``Carpet``Marble``Vinyl``Tile``PouredConcrete``Metal``Glass``Laminate` |
| `window_treatment_type` | `string | null` | Refers to the type of window treatment that covers the windows. `Blinds``Drapes``VerticalBlinds``HorizontalBlinds``Shades``PlantationShutters``CafeShutters``RollerShades``RomanShades``CellularHoneycombShades``SolarShades``PleatedShades``Curtains``BlackoutCurtains``ThermalCurtains``Valances``Cornices``WindowFilm``StainedGlass``BambooShades``WoodShades``WovenShades` |
| `is_finished` | `boolean` | Whether the room is finished (especially important for basements, attics, garages). |
| `furnished` | `string | null` | Indicates whether the room is furnished and to what extent. `Furnished``Unfurnished``Partially Furnished` |
| `paint_condition` | `string | null` | Visual state of paint within the room. `New``Good``Worn``Peeling` |
| `flooring_wear` | `string | null` | Observed condition of the flooring. `Pristine``Good``Moderate``Worn``Damaged` |
| `clutter_level` | `string | null` | Amount of visible clutter or personal items in the room. `Staged``Moderate``Heavy` |
| `visible_damage` | `string | null` | List of visible damage types (e.g. mold, stains, cracks, broken fixtures). |
| `countertop_material` | `string | null` | Material of visible countertops, if present. `Granite``Quartz``Marble``Laminate``Wood``Tile``Concrete` |
| `cabinet_style` | `string | null` | Visual cabinet style present in the room, if any. `Modern``Shaker``Traditional``Flat Panel``Glass Front` |
| `fixture_finish_quality` | `string | null` | `Basic``Mid-range``Luxury` |
| `design_style` | `string | null` | Dominant design style observed in the room. `Modern``Traditional``Rustic``Eclectic``Minimalist``Transitional` |
| `natural_light_quality` | `string | null` | Assessment of natural light availability. `Abundant``Moderate``Limited` |
| `decor_elements` | `string | null` | List of prominent design elements. `Vaulted Ceiling``Coffered Ceiling``Beamed Ceiling``Tray Ceiling``Accent Wall``Exposed Brick``Crown Molding``Wainscoting``Built-In Shelving``Wall Paneling` |
| `pool_type` | `string | null` | Specifies the structural or functional type of the pool if applicable to this room. `SaltWater``AboveGround``Concrete``Heated``BuiltIn``Plunge``Lap``Infinity``Fiberglass``Vinyl``Natural` |
| `pool_equipment` | `string | null` | List of visible pool-related equipment such as pumps, heaters, or covers. |
| `spa_type` | `string | null` | Specifies the type of spa or hot tub present, if applicable. `Jacuzzi``InGround``Rooftop``WoodFiredHotTub``JapaneseSoakingTub``Saltwater``Heated` |
| `safety_features` | `string | null` | Visible safety features such as fencing, alarms, slip-resistant surfaces, or pool covers. `Fencing``PoolCover``Alarm``SelfClosingGate``SlipResistantSurface``Lifebuoy``WarningSignage``SurveillanceCamera``Lighting` |
| `view_type` | `string | null` | The dominant view visible from this room. `Courtyard``Ocean``City``Garden``Bay``Marina``Mountain``Park``Waterfront``Street` |
| `lighting_features` | `string | null` | Observed lighting fixtures and types in room. `Recessed``Track``Pendant``Chandelier``FlushMount``WallSconces``NaturalLight``Skylight` |
| `condition_issues` | `string | null` | AI-observed visual condition issues in the room. `PeelingPaint``VisibleMold``WaterStains``DamagedDrywall``Clutter``Unfinished``Unclean``PersonalItemsVisible` |
| `is_exterior` | `boolean` | Indicates whether the space is exterior or interior. |
| `pool_condition` | `string | null` | Overall visible condition of the pool structure (tiles, lining, coping, etc.). `New``Good``Worn``Needs Repair``Damaged``Unknown` |
| `pool_surface_type` | `string | null` | The visible material or finish used for the pool’s interior surface. `Concrete``Tile``Vinyl Liner``Fiberglass``Painted``Natural Stone``Unknown` |
| `pool_water_quality` | `string | null` | The observed quality or clarity of the pool water in the image. `Clear``Slightly Cloudy``Cloudy``Green``Debris Present``Drained``Covered``Unknown` |
| `kitchen_renovation_date` | `string | null` | Date this kitchen was last remodeled (BLD/RES/COM). |
| `bathroom_renovation_date` | `string | null` | Date this bathroom was last remodeled (BLD/RES/COM/PLU/ELE). |
| `installation_date` | `string | null` | Date this layout/space was installed (BLD/RES/COM). |
| `flooring_installation_date` | `string | null` | Date flooring in this space was installed (BLD/RES/COM). |
| `pool_installation_date` | `string | null` | Date pool was installed (POL). |
| `spa_installation_date` | `string | null` | Date spa/hot tub was installed (POL/BLD). |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# loan
# loan
An existing mortgage against the property: amounts, terms, rates, payment schedule and status.
Represents a mortgage loan with comprehensive financial terms, conditions, and status information.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
Encumbrances determine whether a transaction closes and on what timeline. An open lien is a payoff; a chain of assignments with a gap is a title problem; a loan in default is a different transaction entirely.
The class carries the loan as recorded against the property, which is a different thing from the loan being originated — that is the mortgage model's `loan`.
## In practice
Recorded loan data comes from the deed index rather than from a servicer, so it reflects what was filed rather than the current balance. Treating a recorded original amount as an outstanding balance is the common error, and the class keeps the recording data alongside so the distinction stays visible.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `borrower_count` | `integer | null` | The number of borrowers obligated on the note. |
| `end_date` | `string | null` | The end date is the date when the borrower is expected to have fully repaid the mortgage loan and the mortgage is considered to be fully paid off. This date is typically specified in the mortgage agreement and is calculated based on the term of the mortgage, which is the length of time the borrower has to repay the loan. |
| `lien_priority_type` | `string | null` | Defines the priority of claims against the property in the event of default or foreclosure. The priority determines the sequence of debt repayment if the property is sold or foreclosed on `FirstLien``ThirdLien``FourthLien``SecondLien` |
| `loan_amount` | `decimal` | Loan amount refers to the total amount of money that a borrower borrows from a lender to purchase a property. This amount is typically based on the purchase price of the property, minus any down payment that the borrower is able to make. |
| `loan_closing_date` | `string | null` | The date on which the mortgage loan is officially closed and the loan funds are disbursed to the borrower. |
| `loan_purpose_type` | `string | null` | Specifies the primary reason or purpose for which the loan was taken. `Refinance``Purchase``MortgageModification``Unknown` |
| `lender_name` | `string | null` | The name of the institution or company that originated or currently owns the loan. |
| `mortgage_type` | `string | null` | Mortgage type refers to the specific type of mortgage loan that a borrower obtains to finance the purchase or refinance of a property. There are several different types of mortgage loans, each with its own set of features, eligibility requirements, and interest rates. `Conventional``Va``UsdaRuralDevelopment``LocalAgency``Fha``PublicAndIndianHousing``StateAgency` |
| `note_amount` | `decimal` | The amount to be repaid as disclosed on the note. |
| `note_date` | `string | null` | The date on the note. |
| `note_rate_percent` | `decimal` | The actual interest rate as disclosed on the note. |
| `occupancy` | `string | null` | Occupancy type refers to the way in which a property is used or occupied by its owner or tenant. Occupancy type is used in determining the terms of a mortgage or loan and the level of risk associated with a property. `SecondHome``PrimaryResidence``Investment` |
| `prepayment_penalty_indicator` | `boolean` | Indicates whether the loan includes a penalty charged to the borrower in the event of prepayment. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# lot
# lot
The land around the structure: dimensions, topography, landscaping, and the exterior characteristics recorded against the parcel.
The Lot class captures comprehensive information about the land parcel and exterior property characteristics surrounding a structure, including physical dimensions, surface features, and condition assessments.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Lot size and shape set what can be built and what a buyer is actually acquiring. Two identical houses on a quarter-acre and a two-acre lot are different transactions, and the difference is not proportional to the extra land.
## In practice
The class carries recorded dimensions rather than a computed area where the source gives them, because the two disagree often enough to matter — an irregular parcel's stated acreage and its recorded frontage and depth are frequently inconsistent in the source, and collapsing them to one number hides that.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `lot_type` | `string | null` | Refers to characteristics associated with a lot and structure. `GreaterThanOneQuarterAcre``PavedRoad``LessThanOrEqualToOneQuarterAcre` |
| `lot_size_acre` | `number | null` | The size of the lot in acre. |
| `lot_length_feet` | `integer | null` | The length of the lot in feet (typically the side parallel to the street). |
| `lot_width_feet` | `integer | null` | The width of the lot in feet (typically the depth of the property from front to back). |
| `lot_area_sqft` | `integer | null` | Total land size in square feet for a property |
| `landscaping_features` | `string | null` | Features associated with the landscaping on the lot. `MatureTrees``ManicuredGarden``OvergrownVegetation``FlowerBeds``Planters``Lawn` |
| `view` | `string | null` | Descriptive tag of the view from the lot. `OceanView``Waterfront``MountainView``CitySkylineView``ParkView` |
| `fencing_type` | `string | null` | `Wood``ChainLink``Vinyl``Aluminum``WroughtIron``Bamboo``Composite``Privacy``Picket``SplitRail``Stockade``Board``PostAndRail``Lattice` |
| `fence_height` | `string | null` | `3ft``4ft``5ft``6ft``8ft``10ft``12ft` |
| `fence_length` | `string | null` | `25ft``50ft``75ft``100ft``150ft``200ft``300ft``500ft``1000ft` |
| `driveway_material` | `string | null` | The material of the driveway on the lot. `Concrete``Asphalt``Pavers``Gravel` |
| `driveway_condition` | `string | null` | `Good``Cracked``Stained``Worn` |
| `lot_condition_issues` | `string | null` | AI-observed lot-level maintenance or neglect issues. `OvergrownWeeds``Clutter``TrashPiles``BrokenFence``CrackedDriveway` |
| `site_lighting_type` | `string | null` | Type and height of outdoor lighting fixtures on the lot `LightStandard10to30ft``LightStandardUnder10ft``LightStandardOver30ft``FloodLight``SecurityLight``PathLight``None` |
| `site_lighting_fixture_count` | `number | null` | Total number of light fixtures installed on the property |
| `site_lighting_installation_date` | `string | null` | Installation date of site lighting (YYYY-MM-DD or YYYY) |
| `paving_type` | `string | null` | Primary paving material used on the lot `Asphalt``Concrete``Gravel``Pavers``Brick``Composite``None` |
| `paving_area_sqft` | `number | null` | Total paved area in square feet |
| `paving_installation_date` | `string | null` | Installation date of paving (YYYY-MM-DD or YYYY) |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# parcel
# parcel
The land parcel as the jurisdiction records it: its identifier, and the formatted variants of that identifier the source publishes.
Represents a parcel of land with unique identifiers and formatted representations for property management and legal documentation purposes.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
The parcel identifier is how a jurisdiction refers to a property in every record it keeps — the tax roll, the deed index, the permit file. Resolving one across those sources is what turns four unrelated documents into one property history.
## In practice
Jurisdictions format the same identifier several ways. A county will publish a punctuated form on the assessor page, an unpunctuated form in a bulk file, and a third form in the clerk's index, so the class carries the formatted variants rather than picking one and losing the ability to match the others.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `parcel_identifier` | `string` | Each parcel of land has a unique Parcel ID that distinguishes it from all other parcels within the jurisdiction. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# person
# person
An individual: name, demographics, identification, citizenship and the biographical detail the source records.
Represents an individual person with comprehensive personal information including name, demographics, identification, citizenship status, and biographical details.
The question it answers
## Who owns it, and what does that imply?
A deed names its parties as strings. Resolving those strings to a person and a mailing address is what separates an owner-occupant from an investor, and what links one owner to the rest of a portfolio.
Other classes answering this question
## Why it matters
Ownership is the question this class exists to answer. A deed names parties as strings, and turning those strings into people is what separates an owner-occupant from an investor and links one owner to the rest of a portfolio.
## In practice
Name parsing is the work. County records are upper case, comma-ordered, inconsistently suffixed, and carry markers that are not part of a name — trustee abbreviations, estate markers, and a deceased marker among them. The normaliser carries checked-in vocabularies for suffixes, surname prefixes and company keywords, and the presence of a deceased marker and a trustee abbreviation in those lists is the sign they were written against real deed data rather than invented.
The first decision is whether a party string is a person at all, because the same field carries both individuals and entities.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `birth_date` | `string | null` | A birth date is the date on which a person was born. It typically includes the day, month, and year of an individual's birth and is used to determine their age. |
| `first_name` | `string` | A person's first name is the name that they are given at birth or during infancy, and it is typically used to identify them in a personal or informal context. |
| `last_name` | `string` | A person's last name, also known as surname or family name, is typically the name that is shared by all members of their immediate family. |
| `middle_name` | `string | null` | The middle name of the individual represented by the parent object |
| `prefix_name` | `string | null` | Common honorifics or titles preceding names. Adjust this list based on cultural or domain-specific requirements. `Mr.``Mrs.``Ms.``Miss``Mx.``Dr.``Prof.``Rev.``Fr.``Sr.``Br.``Capt.``Col.``Maj.``Lt.``Sgt.``Hon.``Judge``Rabbi``Imam``Sheikh``Sir``Dame` |
| `suffix_name` | `string | null` | Suffixes typically denote generational titles, academic degrees, or professional certifications. `Jr.``Sr.``II``III``IV``PhD``MD``Esq.``JD``LLM``MBA``RN``DDS``DVM``CFA``CPA``PE``PMP``Esq.``Emeritus``Ret.` |
| `us_citizenship_status` | `string | null` | Citizenship status refers to an individual's legal status as a citizen or non-citizen of a country. In the United States, citizenship status is determined by birthright, naturalization, or other legal means. `NonPermanentResidentAlien``NonPermResidentAlien``PermResidentAlien``PermanentResidentAlien``USCitizenAbroad``USCitizen``ForeignNational` |
| `veteran_status` | `boolean | null` | Veteran status refers to an individual's status as a former member of the armed forces. In the United States, a person is considered a veteran if they have served in the active military, naval, or air service and were discharged or released from that service under conditions other than dishonorable. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# property_improvement
# property_improvement
Permitted work on a property: the scope, the date, the declared valuation, the contractor, and whether it reached final inspection.
The question it answers
## What changed since it was built?
Two physically identical houses on the same street diverge by six figures if one had a gut renovation. Photographs show current condition but not cost basis, scope, or recency. A permit records all three, and a pulled but unfinalised permit is a leading indicator priced differently again. Permits are issued by municipalities rather than counties, which is an order of magnitude more integration surface than parcel data and the reason incumbent coverage is thin.
Other classes answering this question
## Why it matters
The permit record is what makes a renovation datable and costable. The declared valuation on the permit is the contractor's own figure at the time of filing, which is a lower bound on spend rather than an appraisal, and the scope text is the description the jurisdiction accepted.
Recency comes from the filing and completion dates, which is why the class holds both rather than a single date.
The source dictionary carries no definition for this class.
## In practice
Acquisition is the hard part, and it is a sourcing problem rather than a technical one. Permits are issued by municipalities, and the recorded estimate puts the number of permit-issuing bodies in the tens of thousands against roughly 3,300 counties.
Coverage therefore reports permits as a separate surface: a jurisdiction served for property records is not automatically served for permits.
An unfinalised permit is a distinct state rather than missing data, which is why the inspection record is its own class — see `inspection`.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `improvement_type` | `string | null` | `GeneralBuilding``ResidentialConstruction``CommercialConstruction``BuildingAddition``StructureMove``Demolition``PoolSpaInstallation``Electrical``MechanicalHVAC``GasInstallation``Roofing``Fencing``DockAndShore``FireProtectionSystem``Plumbing``ExteriorOpeningsAndFinishes``MobileHomeRV``LandscapeIrrigation``ScreenEnclosure``ShutterAwning``SiteDevelopment``CodeViolation``Complaint``ContractorLicense``Sponsorship``StateLicenseRegistration``AdministrativeApproval``AdministrativeAppeal``BlueSheetHearing``PlannedDevelopment``DevelopmentOfRegionalImpact``Rezoning``SpecialExceptionZoning``Variance``ZoningExtension``ZoningVerificationLetter``RequestForRelief``WaiverRequest``InformalMeeting``EnvironmentalMonitoring``Vacation``VegetationRemoval``ComprehensivePlanAmendment``MinimumUseDetermination``TransferDevelopmentRightsDetermination``MapBoundaryDetermination``TransferDevelopmentRightsCertificate``UniformCommunityDevelopment``SpecialCertificateOfAppropriateness``CertificateToDig``HistoricDesignation``PlanningAdministrativeAppeal``WellPermit``Solar``TestBoring``ExistingWellInspection``NaturalResourcesComplaint``NaturalResourcesViolation``LetterWaterSewer``UtilitiesConnection``DrivewayPermit``RightOfWayPermit` |
| `improvement_status` | `string | null` | Current status of the improvement project. `Completed``InProgress``Planned``Permitted``OnHold``Cancelled` |
| `completion_date` | `string | null` | Date when the improvement work was completed. |
| `contractor_type` | `string | null` | Type of contractor or method used for the work. `GeneralContractor``Specialist``DIY``PropertyManager``Builder``HandymanService``Unknown` |
| `permit_required` | `boolean` | Whether the improvement required building permits. |
| `permit_number` | `string | null` | Jurisdiction record/permit number (e.g., MEC2025-05360). |
| `application_received_date` | `string | null` | Date the application was received. |
| `permit_issue_date` | `string | null` | Date the permit was issued. |
| `final_inspection_date` | `string | null` | Date of final inspection approval. |
| `permit_close_date` | `string | null` | Date the permit record was closed/complete. |
| `improvement_action` | `string | null` | Nature of the work. `New``Replacement``Repair``Alteration``Addition``Remove``Other` |
| `is_owner_builder` | `boolean | null` | Whether improvement is done by owner versus hiring a contractor |
| `is_disaster_recovery` | `boolean | null` | Whether the work is associated with disaster recovery. |
| `private_provider_plan_review` | `boolean | null` | Private provider used for plan review. |
| `private_provider_inspections` | `boolean | null` | Private provider used for inspections. |
| `fee` | `decimal` | Cost associated with acquiring the property improvement/permits. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Santa Clara, California
How a new jurisdiction is brought online
---
# property_ranking_overall
# property_ranking_overall
Composite scores for a property across climate, safety, wellness, ambience and location quality.
Overall property ranking and assessment scores based on multiple factors including climate, safety, wellness, ambience, and location quality.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
A composite score is a convenience over the classes that produce it, and it is recorded as its own class so a consumer can see the components rather than only the roll-up.
## In practice
The components are the environmental, safety, transport and school classes. Where one of those is thin for a jurisdiction the composite inherits the gap, which is why the components stay addressable rather than being collapsed.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | CRLF-formatted and JSON-stringified HTTPS request from which this data can be retrieved. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `overall_ranking_score` | `number` | Overall property ranking score out of 100. |
| `ranking_percentile` | `string | null` | Percentile ranking description (e.g., 'top 5% of similar listings'). |
| `climate_score` | `number` | Climate assessment score. |
| `safety_grade` | `string | null` | Safety grade assessment. `A+``A``A-``B+``B``B-``C+``C``C-``D+``D``D-``F` |
| `wellness_score` | `number` | Wellness and health factors score. |
| `ambience_score` | `number` | Ambience and livability score. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# property_seed
# property_seed
The minimum identifying set for a property: enough to address it in a source system before anything else is known.
A minimum set of house property seed data containing essential identifying information for property records.
The question it answers
## Who owns it, and what does that imply?
A deed names its parties as strings. Resolving those strings to a person and a mailing address is what separates an owner-occupant from an investor, and what links one owner to the rest of a portfolio.
Other classes answering this question
## Why it matters
This is where a jurisdiction run starts. The seed carries the parcel identifier and the source location, which is everything needed to fetch the record and nothing more.
Separating the seed from the record is what allows acquisition to be planned before extraction is written: a jurisdiction's parcel list can be assembled and counted while the mapping scripts for it are still being generated.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `entry_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `parcel_id` | `string` | A unique identifier for the property parcel as assigned by the local assessor or jurisdiction. |
| `prior_parcel_id` | `string` | The parcel identification number (parcel ID or folio) that was previously assigned to the property before it was changed due to a split, combination, renumbering, or administrative update by the property appraiser. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# property
# property
The root record for a parcel of real estate: its identifiers, its legal description, and the characteristics every other class hangs off.
The Property class serves as the foundational data structure for capturing essential characteristics and legal identifiers of real estate properties, providing comprehensive documentation for financing, legal, and classification purposes.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Everything else in the model attaches here. A structure, a lot, a tax position and a sales history are all statements about one property, and the identifiers on this class are what make them the same property rather than four records that happen to share an address.
## In practice
Identity is the hard part, not the attributes. A parcel is identified by the jurisdiction's own parcel number, which is formatted differently in every county and is not unique across them; the address is a second identifier that is frequently wrong or absent. Both are carried, and neither is trusted alone.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `historic_designation` | `boolean` | True if the property has been granted official historic designation by a local, state, or national authority; false otherwise. |
| `livable_floor_area` | `string | null` | The total square footage of attached, livable area excluding balconies, porches, garages, car ports, elevators, and utility rooms. |
| `area_under_air` | `string | null` | Also called “Living Area Under Air” or “Heated Living Area,” this refers to the total finished square footage of a building that is served by a permanent heating and/or cooling system (HVAC). |
| `total_area` | `string | null` | The total square footage of the property, including all areas, such as the living area, garage, and basement. |
| `number_of_units_type` | `string | null` | number of units type in mortgage banking refers to the classification of a property based on the number of units it contains. This classification is important for determining the type of loan that can be used to finance the property, as well as the underwriting requirements and guidelines that must be followed. Typically, properties are classified into one of three categories: single-family homes, multi-family homes (e.g. duplexes, triplexes, fourplexes), and larger multi-unit properties (e.g. apartment buildings). The number of units type is used to determine the loan-to-value (LTV) ratio, debt-to-income (DTI) ratio, and other loan requirements, as well as the risk associated with the property. For example, rdf:type single-family home may have more favorable lending terms than rdf:type multi-unit property, as the latter may be seen as rdf:type higher risk due to the potential for multiple tenants and increased maintenance costs. `One``Two``OneToFour``Three``Four``TwoToFour` |
| `number_of_units` | `integer | null` | The number of units for a property refers to how many separate, self-contained dwelling or rental spaces exist within that property. |
| `parcel_identifier` | `string` | Each parcel of land has a unique Parcel ID that distinguishes it from all other parcels within the jurisdiction. |
| `ownership_estate_type` | `string | null` | A value from a MISMO prescribed list that specifies the ownership interest in the property. `Condominium``Cooperative``LifeEstate``Timeshare``OtherEstate``FeeSimple``Leasehold``RightOfWay``NonWarrantableCondo``SubsurfaceRights` |
| `property_legal_description_text` | `string | null` | A detailed legal description of the property, often used in legal documents and contracts. This typically outlines the exact boundaries, dimensions, and location of the property as recognized by local or state governments. |
| `property_structure_built_year` | `integer | null` | The year in which the dwelling on the property was completed. |
| `property_effective_built_year` | `integer | null` | The year assigned by the property appraiser that reflects the building’s overall condition, age, and the impact of major renovations or additions, rather than the actual calendar year of original construction. |
| `build_status` | `string | null` | Indicates the current construction and improvement status of the property. VacantLand indicates undeveloped land with no structures, Improved indicates land with completed structures or improvements, and UnderConstruction indicates active construction or development in progress. `VacantLand``Improved``UnderConstruction` |
| `property_type` | `string` | Property type refers to the classification of a real estate property based on its characteristics, usage, and zoning designation. Property types can include residential, commercial, industrial, agricultural, and mixed-use properties. `Cooperative``Condominium``Modular``ManufacturedHousingMultiWide``Pud``Timeshare``2Units``DetachedCondominium``Duplex``SingleFamily``MultipleFamily``3Units``ManufacturedHousing``ManufacturedHousingSingleWide``4Units``Townhouse``NonWarrantableCondo``VacantLand``Retirement``MiscellaneousResidential``ResidentialCommonElementsAreas``MobileHome``Apartment``MultiFamilyMoreThan10``MultiFamilyLessThan10``LandParcel``Building``Unit``ManufacturedHome` |
| `structure_form` | `string | null` | Describes the physical form or architectural configuration of the dwelling structure. This classification identifies the attachment style and unit type, such as single-family detached homes, townhouses, multi-unit buildings, or manufactured homes, which impacts property valuation, lending guidelines, and zoning considerations. `SingleFamilyDetached``SingleFamilySemiDetached``TownhouseRowhouse``Duplex``Triplex``Quadplex``MultiFamily5Plus``ApartmentUnit``Loft``ManufacturedHomeOnLand``ManufacturedHomeInPark``MultiFamilyMoreThan10``MultiFamilyLessThan10``MobileHome``ManufacturedHousingMultiWide``ManufacturedHousing``ManufacturedHousingSingleWide``Modular` |
| `property_usage_type` | `string | null` | A value from a MISMO prescribed list that specifies the intended usage of the property by the borrower. `Residential``Commercial``Industrial``Agricultural``Recreational``Conservation``Retirement``ResidentialCommonElementsAreas``DrylandCropland``HayMeadow``CroplandClass2``CroplandClass3``TimberLand``GrazingLand``OrchardGroves``Poultry``Ornamentals``Church``PrivateSchool``PrivateHospital``HomesForAged``NonProfitCharity``MortuaryCemetery``ClubsLodges``SanitariumConvalescentHome``CulturalOrganization``Military``ForestParkRecreation``PublicSchool``PublicHospital``GovernmentProperty``RetailStore``DepartmentStore``Supermarket``ShoppingCenterRegional``ShoppingCenterCommunity``OfficeBuilding``MedicalOffice``TransportationTerminal``Restaurant``FinancialInstitution``ServiceStation``AutoSalesRepair``MobileHomePark``WholesaleOutlet``Theater``Entertainment``Hotel``RaceTrack``GolfCourse``LightManufacturing``HeavyManufacturing``LumberYard``PackingPlant``Cannery``MineralProcessing``Warehouse``OpenStorage``Utility``RiversLakes``SewageDisposal``Railroad``TransitionalProperty``ReferenceParcel``NurseryGreenhouse``AgriculturalPackingFacility``LivestockFacility``Aquaculture``VineyardWinery``DataCenter``TelecommunicationsFacility``SolarFarm``WindFarm``NativePasture``ImprovedPasture``Rangeland``PastureWithTimber``Unknown` |
| `subdivision` | `string | null` | Subdivision is the term used to describe a defined area within a city or community that has been divided into individual plots or lots, usually intended for residential or commercial development. It is often formally designated by the township or municipality. |
| `zoning` | `string | null` | Zoning is a system of land-use regulation created by local governments to control how property and land within a community can be used. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# safety_security
# safety_security
Safety metrics for the property's location: crime rates, emergency-services response, and an overall assessment.
Safety and security metrics including crime rates, emergency services response times, and overall safety assessments.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Safety at location level is one of the inputs buyers weight most heavily and one of the least consistently available, because the reporting geography rarely matches the parcel geography.
## In practice
The figures come from published sources at whatever geography those sources use, which is usually a reporting district rather than a parcel. The class records what was published rather than interpolating to the parcel, so a consumer can decide how to treat the mismatch.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `crime_rate` | `string | null` | Overall crime rate assessment for the area. `VeryLow``Low``Moderate``High``VeryHigh` |
| `crime_rate_comparison` | `string | null` | Comparison to national average (e.g., '70% below national avg'). |
| `emergency_services_response` | `string | null` | Emergency services response time quality. `FastResponse``GoodResponse``AverageResponse``SlowResponse` |
| `emergency_response_time` | `string | null` | Specific response time range (e.g., '5-7 min response time'). |
| `overall_safety_grade` | `string | null` | Overall safety grade for the area. `A+``A``A-``B+``B``B-``C+``C``C-``D+``D``D-``F` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# sales_history
# sales_history
The recorded transfer history for a property: amount, date, and the type of each transfer.
The question it answers
## What are the comparables, really?
A recorded deed is the legal source of truth for a transfer: instrument type, consideration, parties, and date. That is what separates an arm's-length sale from a quitclaim between relatives, an estate transfer, a foreclosure, or an investor flip. A comp set that silently includes non-arm's-length transfers is biased before the model sees it.
Other classes answering this question
## Why it matters
One row per transfer, linked to the deed that recorded it. Holding the full history rather than the last sale is what allows a consumer to filter to arm's-length transactions before computing anything, and to see a flip pattern that a single most-recent-sale field hides.
The source dictionary carries no definition for this class.
## In practice
The transfer and the document are separate classes because the cardinality differs: one deed can convey several parcels, and one parcel accumulates many deeds. Linking them rather than embedding is what keeps both directions navigable.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `ownership_transfer_date` | `string | null` | The date of the transfer of ownership of real property as recognized in the jurisdiction in which it is located. |
| `purchase_price_amount` | `decimal` | The total dollar amount paid by the borrower for the property. The purchase price is presented on the offer to purchase. |
| `sale_type` | `—` | `ProbateSale``ShortSale``CourtOrderedNonForeclosureSale``ReoPostForeclosureSale``TrusteeNonJudicialForeclosureSale``RelocationSale``TrusteeJudicialForeclosureSale``TypicallyMotivated` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# school
# school
The schools serving the property: name, type, ranking, and the attendance relationship.
Represents an educational institution such as an elementary, middle, or high school.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
School assignment is one of the largest location premiums in residential pricing, and it is a boundary question rather than a distance question — the nearest school is frequently not the assigned one.
## In practice
The class holds the institution; the attendance relationship holds the link to a property. Keeping them separate is what allows a boundary change to be recorded once rather than against every parcel it affects.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `school_name` | `string | null` | The name of the school. |
| `school_type` | `string | null` | The type of school. `Elementary``Middle``High` |
| `school_ranking` | `string | null` | Ranking of the school. |
| `rating_score` | `number` | Numerical rating score out of 10. |
| `grade_rating` | `string | null` | Letter grade rating for the school. `A+``A``A-``B+``B``B-``C+``C``C-``D+``D``D-``F` |
| `distance_miles` | `number` | Distance from the property to the school in miles. |
| `description` | `string | null` | Additional description about the school's programs, reputation, or special features. |
| `overall_district_rating` | `number` | Overall school district rating out of 10. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# structure
# structure
The building itself: construction materials, condition, architectural style, and the structural elements the assessor recorded.
Represents the physical building structure with detailed architectural and construction information including materials, conditions, styles, and structural elements.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Everything about the building that is not its shape or its rooms. Those are `lot` and `layout`; this class is what the building is made of and what condition it is in.
The distinction matters because the three come from different parts of an assessor's record and are updated on different cycles. Merging them into one property record loses the ability to update the one that changed.
## In practice
The class is wide because assessors record at that granularity: exterior wall material and its condition, primary and secondary, then roof, foundation, framing and finish, each carrying its own condition.
Attachment type carries more than it appears to. Detached, semi-detached and attached distinguish a house from a duplex half from a townhouse, which is a different comparable set rather than a different adjustment on the same one.
Sub-areas are the other field worth knowing. An assessor records areas separately — living area, garage, porch, unfinished space — each flagged for whether it is heated, which is what allows gross living area to be computed rather than taken on trust.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `architectural_style_type` | `string | null` | Refers to the style, structure, and aesthetics of a building. `MidCenturyModern``Contemporary``Victorian``Ranch``Craftsman``Tudor``Minimalist``Colonial``Farmhouse` |
| `attachment_type` | `string | null` | Indicates the structural relationship of the dwelling to other units. 'Attached' means the unit shares walls on both sides with adjacent dwellings (e.g., rowhouse or townhouse); 'SemiDetached' means it shares a wall with one other unit (e.g., duplex); 'Detached' means the unit stands alone with no shared walls. `Attached``SemiDetached``Detached` |
| `exterior_wall_material_primary` | `string | null` | Primary material used for exterior wall cladding and structure. `Brick``Natural Stone``Manufactured Stone``Stucco``Vinyl Siding``Wood Siding``Fiber Cement Siding``Metal Siding``Concrete Block``EIFS``Log``Adobe``Precast Concrete``Curtain Wall` |
| `exterior_wall_material_secondary` | `string | null` | Secondary material used for exterior wall accents or trim. `Brick Accent``Stone Accent``Wood Trim``Metal Trim``Stucco Accent``Vinyl Accent``Decorative Block` |
| `exterior_wall_condition_primary` | `string | null` | Observed condition of the exterior wall materials. `New``Excellent``Good``Fair``Poor``Damaged` |
| `exterior_wall_condition` | `string | null` | Observed condition of the exterior wall materials. `New``Excellent``Good``Fair``Poor``Damaged` |
| `exterior_wall_insulation_type` | `string | null` | Type of insulation used in exterior wall cavities. `Fiberglass Batt``Blown Cellulose``Spray Foam``Rigid Foam Board``Reflective Barrier``Rock Wool``Natural Fiber``Unknown` |
| `exterior_wall_insulation_type_primary` | `string | null` | Type of insulation used in exterior wall cavities. `Fiberglass Batt``Blown Cellulose``Spray Foam``Rigid Foam Board``Reflective Barrier``Rock Wool``Natural Fiber``Unknown` |
| `exterior_wall_condition_secondary` | `string | null` | Observed condition of the exterior wall materials. `New``Excellent``Good``Fair``Poor``Damaged` |
| `exterior_wall_insulation_type_secondary` | `string | null` | Type of insulation used in exterior wall cavities. `Fiberglass Batt``Blown Cellulose``Spray Foam``Rigid Foam Board``Reflective Barrier``Rock Wool``Natural Fiber``Unknown` |
| `flooring_material_primary` | `string | null` | Primary flooring material covering floor surface. `Solid Hardwood``Engineered Hardwood``Laminate``Luxury Vinyl Plank``Sheet Vinyl``Ceramic Tile``Porcelain Tile``Natural Stone Tile``Carpet``Area Rugs``Polished Concrete``Bamboo``Cork``Linoleum``Terrazzo``Epoxy Coating` |
| `flooring_material_secondary` | `string | null` | Secondary flooring material if multiple types are used in different areas. `Solid Hardwood``Engineered Hardwood``Laminate``Luxury Vinyl Plank``Ceramic Tile``Carpet``Area Rugs``Transition Strips` |
| `subfloor_material` | `string | null` | Material used for subfloor structure beneath finish flooring. `Plywood``OSB``Concrete Slab``Engineered Wood``Particle Board``Unknown` |
| `flooring_condition` | `string | null` | Overall condition of flooring materials and installation. `New``Excellent``Good``Fair``Poor``Damaged` |
| `interior_wall_structure_material` | `string | null` | Structural material used for interior wall framing. `Wood Frame``Steel Frame``Concrete Block``Brick``Load Bearing``Non-Load Bearing` |
| `interior_wall_structure_material_primary` | `string | null` | Structural material used for interior wall framing. `Wood Frame``Steel Frame``Concrete Block``Brick``Load Bearing``Non-Load Bearing` |
| `interior_wall_structure_material_secondary` | `string | null` | Structural material used for interior wall framing. `Wood Frame``Steel Frame``Concrete Block``Brick``Load Bearing``Non-Load Bearing` |
| `interior_wall_surface_material_primary` | `string | null` | Primary surface material covering interior walls throughout most of the structure. `Drywall``Plaster``Wood Paneling``Exposed Brick``Exposed Block``Wainscoting``Shiplap``Board and Batten``Tile``Stone Veneer``Metal Panels``Glass Panels``Concrete` |
| `interior_wall_surface_material_secondary` | `string | null` | Secondary material used for interior wall accents, trim, or feature walls. `Wainscoting``Chair Rail``Crown Molding``Baseboards``Wood Trim``Stone Accent``Tile Accent``Metal Accent``Glass Insert``Decorative Panels``Feature Wall Material` |
| `interior_wall_finish_primary` | `string | null` | Primary finish treatment applied over interior wall surfaces. `Paint``Primer and Paint``Textured Paint``Natural Finish``Stain``Clear Coat``Exposed Natural` |
| `interior_wall_finish_secondary` | `string | null` | Secondary finish treatment for accent areas or decorative elements. `Wallpaper``Wall Decals``Decorative Plaster``Faux Finish``Fabric Wall Covering``Murals``Decorative Paint Technique` |
| `interior_wall_condition` | `string | null` | Overall condition of interior wall surfaces and finishes. `New``Excellent``Good``Fair``Poor``Damaged` |
| `roof_covering_material` | `string | null` | Material used for the primary roof covering. `3-Tab Asphalt Shingle``Architectural Asphalt Shingle``Metal Standing Seam``Metal Corrugated``Clay Tile``Concrete Tile``Natural Slate``Synthetic Slate``Wood Shake``Wood Shingle``TPO Membrane``EPDM Membrane``Modified Bitumen``Built-Up Roof``Green Roof System``Solar Integrated Tiles` |
| `roof_underlayment_type` | `string | null` | Type of underlayment beneath roof covering. `Felt Paper``Synthetic Underlayment``Rubberized Asphalt``Unknown` |
| `roof_structure_material` | `string | null` | Material used for roof structural support. `Wood Truss``Wood Rafter``Steel Truss``Concrete Beam``Engineered Lumber` |
| `roof_design_type` | `string | null` | Architectural design of the roof structure. `Gable``Hip``Flat``Mansard``Gambrel``Shed``Saltbox``Butterfly``Bonnet``Clerestory``Dome``Barrel``Combination` |
| `roof_condition` | `string | null` | Visible condition of the roof covering and structure. `New``Excellent``Good``Fair``Poor``Damaged``Leaking` |
| `roof_age_years` | `integer | null` | Estimated age of the roof covering in years. |
| `roof_date` | `string | null` | Date when the roof was built (format: YYYY, YYYY-MM, or YYYY-MM-DD) |
| `gutters_material` | `string | null` | Material used for gutter system. `Aluminum``Vinyl``Steel``Copper``Galvanized Steel` |
| `gutters_condition` | `string | null` | Condition of gutters and downspout system. `New``Good``Fair``Poor``Missing``Damaged` |
| `number_of_stories` | `number | null` | Indicates the total number of above-ground stories (floors) in the structure. |
| `roof_material_type` | `string | null` | Refers to the material a roof is made of. `Manufactured``EngineeredWood``Terazzo``Brick``Wood``CinderBlock``Concrete``Shingle``Composition``Linoleum``Stone``CeramicTile``Block``WoodSiding``ImpactGlass``Carpet``Marble``Vinyl``Tile``PouredConcrete``Metal``Glass``Laminate` |
| `foundation_type` | `string | null` | Type of foundation system supporting the structure. `Slab on Grade``Crawl Space``Full Basement``Partial Basement``Pier and Beam``Basement with Walkout``Stem Wall` |
| `foundation_material` | `string | null` | Primary material used in foundation construction. `Poured Concrete``Concrete Block``Stone``Brick``Treated Wood Posts``Steel Piers``Precast Concrete``Insulated Concrete Forms` |
| `foundation_waterproofing` | `string | null` | Type of waterproofing system used on foundation. `Membrane``Coating``Drainage System``Unknown` |
| `foundation_condition` | `string | null` | Visible condition of the foundation system. `Excellent``Good``Fair``Minor Cracks``Major Cracks``Settling``Water Damage``Unknown` |
| `ceiling_structure_material` | `string | null` | Structural material supporting the ceiling. `Wood Joists``Steel Joists``Concrete``Exposed Beams``Truss System` |
| `ceiling_surface_material` | `string | null` | Material used for ceiling surface finish. `Drywall``Plaster``Wood Planks``Acoustic Tile``Metal Panels``Suspended Grid``Coffered``Tray``Exposed Structure` |
| `ceiling_insulation_type` | `string | null` | Type of insulation above ceiling. `Fiberglass Batt``Blown Insulation``Spray Foam``Rigid Board``Unknown` |
| `ceiling_height_average` | `number | null` | Average ceiling height in feet. |
| `ceiling_condition` | `string | null` | Overall condition of ceiling materials and structure. `New``Excellent``Good``Fair``Poor``Damaged` |
| `exterior_door_material` | `string | null` | Material used for exterior door construction. `Solid Wood``Wood Composite``Steel``Fiberglass``Aluminum``Glass``Vinyl``Wrought Iron``Security Door` |
| `interior_door_material` | `string | null` | Material and construction of interior doors. `Solid Wood``Hollow Core``Solid Core``Glass Panel``Metal``Composite``Molded``Bifold``Pocket Door``Barn Door` |
| `window_frame_material` | `string | null` | Material used for window frame construction. `Vinyl``Wood``Aluminum``Fiberglass``Steel``Composite``Aluminum Clad Wood``Vinyl Clad Wood` |
| `window_glazing_type` | `string | null` | Type and features of window glazing system. `Single Pane``Double Pane``Triple Pane``Low-E Coated``Tempered``Laminated``Impact Resistant``Argon Filled``Tinted``Smart Glass` |
| `window_operation_type` | `string | null` | Operational mechanism and style of windows. `Double Hung``Single Hung``Casement``Sliding``Awning``Picture``Bay``Bow``Garden``Skylights``Jalousie``Fixed` |
| `window_screen_material` | `string | null` | Material used for window screens. `Aluminum``Fiberglass``Pet Screen``Solar Screen` |
| `primary_framing_material` | `string | null` | Primary material used for structural framing system. `Wood Frame``Steel Frame``Concrete Block``Poured Concrete``Masonry``Engineered Lumber``Post and Beam``Log Construction` |
| `secondary_framing_material` | `string | null` | Secondary structural materials for support beams and lintels. `Steel Beams``Engineered Lumber``Concrete Lintels``Wood Beams` |
| `structural_damage_indicators` | `string | null` | Observable indicators of structural damage or issues. `Foundation Cracks``Wall Cracks``Ceiling Cracks``Sagging Floors``Sagging Roof``Door/Window Misalignment``Water Damage``Termite Damage``Settlement Issues``None Observed` |
| `finished_base_area` | `integer | null` | Finished ground-level base area (first-floor footprint) in square feet. |
| `unfinished_base_area` | `integer | null` | Unfinished ground-level base area in square feet. |
| `finished_basement_area` | `integer | null` | Finished basement area in square feet. |
| `unfinished_basement_area` | `integer | null` | Unfinished basement area in square feet. |
| `finished_upper_story_area` | `integer | null` | Finished upper story area (above the ground floor) in square feet. |
| `unfinished_upper_story_area` | `integer | null` | Unfinished upper story or attic/loft space in square feet. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# tax_authority
# tax_authority
A body with the legal right to levy against a property: county, municipal, school district, and special districts.
Represents tax collecting authorities including county, municipal, school district, and other special district entities that have the legal right to levy and collect property taxes.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
A property is taxed by several authorities at once, and the total obligation is the sum of their separate levies. Modelling them separately is what makes the total explainable and what allows a change in one district's rate to be applied without recomputing the rest.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `authority_name` | `string | null` | The name of the government agency or organization that has the legal right to collect taxes (e.g., 'Miami-Dade County', 'City of Miami', 'Miami-Dade School Board'). |
| `authority_account_identifier` | `string | null` | A unique identifier assigned to the tax authority itself, used to distinguish this authority from other tax collecting entities in the system. |
| `authority_category` | `string | null` | The category or type of tax authority that determines its jurisdiction and tax collection scope. `County``Municipal``School Board``School District``Independent School District``Independent``Special District``Water District``Fire District``Library District``Hospital District``Community College District``Transit Authority``Port Authority``Utility District``Improvement District``State``Federal` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# tax_exemption
# tax_exemption
Exemptions applied against a property's assessed value: type, eligibility, amount and status.
Represents property tax exemptions including homestead, senior, portability, and other exemption types.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
Exemptions are the difference between assessed and taxable value, and several of them do not survive a sale. A homestead exemption held by an elderly owner-occupant can be a large share of the current bill and nothing at all to the next owner, so a carrying-cost estimate that reads the current tax figure is wrong by that amount.
## In practice
Portability is recorded because in some states an exemption benefit follows the owner to a new property, which affects the seller's position rather than the property's.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `tax_year` | `integer | null` | The tax year for which the data applies. |
| `tax_rate` | `decimal` | The tax rate associated with the exemption. |
| `exemption_type` | `string | null` | The type of exemption applied to the property. Must be one of the predefined exemption types. `Portability``Homestead``Add. Homestead``Wid/Vet/Dis``Senior``Affordable Housing` |
| `exemption_value` | `decimal` | The value associated with the exemption. |
| `taxable_value_amount` | `decimal` | The taxable value amount of the property. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# tax_jurisdiction
# tax_jurisdiction
The jurisdictions that govern a property for tax purposes, and the identifier each of them uses for it.
The Tax Jurisdiction class captures detailed information about the various tax authorities that govern a property.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
The same parcel carries a different identifier in each authority's records — one in the county assessment roll, another in the municipal levy, a third in the school district's file. Holding those identifiers together is what allows three independently published records to be reconciled to one property.
## In practice
Jurisdiction boundaries do not follow county lines and do not always follow municipal ones. A parcel can sit inside a fire district and a water management district that each publish separately, which is why the class holds a set rather than a single governing body.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `jurisdiction_name` | `string | null` | The name of the tax jurisdiction (e.g., county or city name). |
| `jurisdiction_type` | `string | null` | The type of tax jurisdiction. `County``Municipal``School Board``School District``Independent School District``Independent``Special District``Water District``Fire District``Library District``Hospital District``Community College District``Transit Authority``Port Authority``Utility District``Improvement District``State``Federal` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# tax
# tax
The property's tax position: assessed values, exemptions, amounts due, and payment history.
Represents property tax information including assessed values, exemptions, tax amounts, and payment details.
The question it answers
## Will this close cleanly?
Liens, encumbrances, tax position, and association obligations determine whether a transaction completes and on what timeline.
Other classes answering this question
## Why it matters
Tax is a carrying cost and a valuation signal at once. The assessed value is an independent opinion of value on a published schedule, and the gap between assessed and market value is itself informative in jurisdictions where reassessment is capped.
Delinquency is the closing question: unpaid tax is a lien ahead of a mortgage.
## In practice
The class holds a history rather than a current figure. A single year's assessed value says little; the sequence shows whether the jurisdiction reassesses on sale, on a cycle, or under a cap, which changes what the next year's obligation will be for a buyer.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `tax_year` | `integer | null` | The tax year for which this property tax assessment applies. |
| `property_assessed_value_amount` | `decimal` | The assessed or SOH value of the property used as the basis for property tax calculations for a given tax year. |
| `property_market_value_amount` | `decimal` | The just or market value of the property used as the basis for property tax calculations for a given tax year. |
| `property_building_amount` | `number | null` | The building or improvement value of the property used as the basis for property tax calculations for a given tax year. |
| `property_land_amount` | `number | null` | The land value of the property used as the basis for property tax calculations for a given tax year. |
| `property_exemption_amount` | `number | null` | The total exemption amount applied to the property for a given tax year, reducing the assessed value for tax calculation purposes. |
| `property_taxable_value_amount` | `decimal` | The final property value on which tax is calculated, derived by subtracting the exemption amount from the assessed value. |
| `city_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by the city for property tax calculations for a given tax year. |
| `county_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by the county for property tax calculations for a given tax year. |
| `college_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by the college district for property tax calculations for a given tax year. |
| `hospital_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by the hospital district for property tax calculations for a given tax year. |
| `school_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by the school district for property tax calculations for a given tax year. |
| `special_district_taxable_value_amount` | `decimal` | The taxable value of the property as assessed by any special districts for property tax calculations for a given tax year. |
| `agricultural_valuation_amount` | `decimal` | The agricultural valuation of the property used as the basis for property tax calculations for a given tax year. |
| `homestead_cap_loss_amount` | `decimal` | The homestead cap loss of the property used as the basis for property tax calculations for a given tax year. |
| `building_replacement_cost_amount` | `decimal` | The total replacement cost of the building used as the basis for property tax calculations for a given tax year. |
| `building_depreciated_value_amount` | `decimal` | The total depreciated value of the building used as the basis for property tax calculations for a given tax year. |
| `millage_rate` | `number | null` | The millage rate (also called mill rate) used to calculate property taxes, expressed as the tax amount per $1,000 of assessed value. For example, a millage rate of 3.0107 means $3.0107 in taxes per $1,000 of assessed property value. |
| `monthly_tax_amount` | `number | null` | The calculated property tax amount due for the specific month (if applicable). |
| `yearly_tax_amount` | `number | null` | The calculated property tax amount due for the specific month (if applicable). |
| `period_end_date` | `string | null` | period end date in mortgage banking expenses refers to the date that marks the end of a specific time period for which expenses are being reported. This date is used to determine the duration of the time period for which expenses are being calculated and reported. The period end date can be used to calculate the total expenses for rdf:type specific time period, such as rdf:type month or rdf:type quarter, and can help mortgage companies to track and analyze their expenses over time. The period end date is an important factor in determining the accuracy and completeness of expense reporting in mortgage banking. |
| `period_start_date` | `string | null` | period start date in mortgage banking expenses refers to the date that marks the beginning of a specific time period for which expenses are being reported. This date is used in conjunction with the period end date to determine the duration of the time period for which expenses are being calculated and reported. The period start date can be used to calculate the total expenses for rdf:type specific time period, such as rdf:type month or rdf:type quarter, and can help mortgage companies to track and analyze their expenses over time. The period start date is an important factor in determining the accuracy and completeness of expense reporting in mortgage banking. |
| `first_year_on_tax_roll` | `integer | null` | The first year the parcel (land) was placed on the county’s property tax assessment roll. |
| `first_year_building_on_tax_roll` | `integer | null` | The first year a building (improvement) on the parcel was added to the tax assessment roll. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# transportation_access
# transportation_access
Commute and access quality around the property: walkability, highway access, and transit availability.
Transportation and commute quality including walkability, highway access, and overall commute assessment.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
Access is a location premium whose sign varies by market. A highway interchange nearby is a premium in one metro and a discount in another, so the class records the measurements rather than a single score with the weighting already applied.
## In practice
Walkability, highway proximity and transit availability are held separately because they are separately available. A jurisdiction with no transit has a genuine absence rather than a low score, and collapsing the three into one number makes the two indistinguishable.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `commute_quality` | `string | null` | Overall commute quality assessment. `Excellent``Great``Good``Fair``Poor` |
| `walkability_score` | `number` | Walk Score rating for walkability to amenities. |
| `walkability_description` | `string | null` | Description of walkable amenities and access. |
| `highway_access` | `string | null` | Quality of highway access. `Excellent``Great``Good``Fair``Poor` |
| `major_highways` | `array` | List of major highways and their accessibility. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# unnormalized_address
# unnormalized_address
The raw address exactly as the source system published it, before parsing.
An unnormalized address schema containing raw address data as typically found in source systems before standardization or parsing into individual components.
The question it answers
## Who owns it, and what does that imply?
A deed names its parties as strings. Resolving those strings to a person and a mailing address is what separates an owner-occupant from an investor, and what links one owner to the rest of a portfolio.
Other classes answering this question
## Why it matters
Keeping the original is what makes a parsing failure recoverable. When a parse is wrong, the correction runs against the source string; if only the parsed form were kept, the evidence for the correction would be gone.
## In practice
It is also the input to the extraction pipeline. A jurisdiction run starts from a seed address record in this shape, and the parsed form is produced by the mapping scripts rather than assumed.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `full_address` | `string` | The street address of the property including street number, street name, city, and state and postal code. Format: '123 Main, Springfield, IL' or '456 Oak Ave, Chicago, IL 1003'. |
| `latitude` | `number | null` | Latitude is a coordinate that specifies the north-south position of a point on the Earth's surface. It is an angular measurement, usually expressed in degrees, with values ranging from -90° at the South Pole to +90° at the North Pole. |
| `longitude` | `number | null` | Longitude is a coordinate that specifies the east-west position of a point on the Earth's surface. It is an angular measurement, usually expressed in degrees, with values ranging from -180° to +180°. |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `entry_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `county_jurisdiction` | `string` | The name of the county or local jurisdiction that has authority over the property for tax assessment and administrative purposes. Should not include the word 'County' in the value. `Dallas``Miami Dade``Broward``Palm Beach``Lee``Hillsborough``Orange``Pinellas``Polk``Duval``Brevard``Pasco``Volusia``Sarasota``Collier``Marion``Manatee``Charlotte``Lake``Osceola``St. Lucie``Seminole``Escambia``St. Johns``Citrus``Bay``Santa Rosa``Hernando``Okaloosa``Highlands``Leon``Alachua``Clay``Sumter``Putnam``Martin``Indian River``Walton``Monroe``Flagler``Nassau``Levy``Washington``Jackson``Suwannee``Columbia``Hendry``Okeechobee``Gadsden``Wakulla``DeSoto``Gulf``Taylor``Franklin``Dixie``Madison``Bradford``Hardee``Gilchrist``Holmes``Calhoun``Hamilton``Baker``Jefferson``Glades``Lafayette``Union``Liberty``Fort Bend``Collin``Allegheny``Hunt``Wood``Burnet``San Patricio``Wise``Nacogdoches``Waller``Cherokee``Navarro``Medina``Alameda``Alpine``Amador``Butte``Calaveras``Colusa``Contra Costa``Del Norte``El Dorado``Fresno``Glenn``Humboldt``Imperial``Inyo``Kern``Kings``Lake``Lassen``Los Angeles``Madera``Marin``Mariposa``Mendocino``Merced``Modoc``Mono``Monterey``Napa``Nevada``Orange``Placer``Plumas``Riverside``Sacramento``San Benito``San Bernardino``San Diego``San Francisco``San Joaquin``San Luis Obispo``San Mateo``Santa Barbara``Santa Clara``Santa Cruz``Shasta``Sierra``Siskiyou``Solano``Sonoma``Stanislaus``Sutter``Tehama``Trinity``Tulare``Tuolumne``Ventura``Yolo``Yuba``Ellis` |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# utility
# utility
The systems serving the property: heating, cooling, water, sewer, electrical, and the energy features recorded against them.
The question it answers
## What is this house, physically?
The feature vector, taken from the source of record rather than from a listing agent. Assessor and parcel records are authoritative; listing fields are agent-entered, inconsistent between markets, and absent entirely for a property that was never listed.
Other classes answering this question
## Why it matters
The utility set is a cost and a risk. Well and septic rather than municipal water and sewer changes the carrying cost, the inspection requirements and the financeability; an ageing heating system is a near-term capital call.
The source dictionary carries no definition for this class.
## In practice
The extraction is one of the five scripts written per jurisdiction, because utility recording is where county formats diverge most — the same heating configuration appears as a code in one county, a free-text description in the next, and a set of separate indicator fields in a third.
## Properties
| Property | Type | Definition |
| --- | --- | --- |
| `source_http_request` | `object` | HTTP request configuration for retrieving this data. |
| `request_identifier` | `string | null` | Identifier value that should be substituted into the source HTTP request to retrieve this specific data. |
| `cooling_system_type` | `string | null` | Refers to the type of cooling system used in the structure. `CeilingFans``Electric``Ductless``Hybrid``CentralAir``WindowAirConditioner``WholeHouseFan``CeilingFan``GeothermalCooling``Zoned` |
| `heating_system_type` | `string | null` | Refers to the type of heating system used in the structure. `ElectricFurnace``Electric``GasFurnace``Ductless``Radiant``Solar``HeatPump``Central``Baseboard``Gas` |
| `heating_fuel_type` | `string | null` | Primary energy source used by the heating system. `Electric``NaturalGas``Propane``Oil``Kerosene``WoodPellet``Wood``Geothermal``Solar``DistrictSteam``Other` |
| `public_utility_type` | `string | null` | Refers to the type of public utility available to a structure. `WaterAvailable``ElectricityAvailable``SewerAvailable``NaturalGasAvailable``CableAvailable``UndergroundUtilities` |
| `sewer_type` | `string | null` | Refers to the type of sewer used in the structure. `Sanitary``Public``Combined``Septic` |
| `water_source_type` | `string | null` | Refers to the type of water source used in the structure. `Well``Aquifer``Public` |
| `plumbing_system_type` | `string | null` | Refers to the type of plumbing system used in the structure. `Copper``PEX``PVC``GalvanizedSteel``CastIron` |
| `plumbing_system_type_other_description` | `string | null` | A free-form field to capture detail when Other is selected for the plumbing system type. |
| `plumbing_fixture_count` | `integer | null` | Total number of plumbing fixtures installed in the property (e.g., toilets, sinks, urinals, floor drains) |
| `plumbing_fixture_type_primary` | `string | null` | Primary type of plumbing fixture. Use 'Mixed' for properties with multiple fixture types. `Toilet``Sink``Urinal``FloorDrain``ServiceSink``UtilitySink``WaterFountain``HoseBib``ShowerHead``Bathtub``Dishwasher``WashingMachine``Mixed``Other` |
| `plumbing_fixture_quality` | `string | null` | Overall quality level of plumbing fixtures `Economy``Standard``Fair``Good``Excellent``Luxury` |
| `electrical_panel_capacity` | `string | null` | Describes the amperage or capacity of the electrical panel, e.g. '100 Amp', '200 Amp'. |
| `electrical_wiring_type` | `string | null` | Specifies the type of electrical wiring used in the structure. `Copper``Aluminum``KnobAndTube` |
| `hvac_condensing_unit_present` | `string | null` | Indicates if an HVAC condensing unit is present, as visible externally. |
| `electrical_wiring_type_other_description` | `string | null` | A free-form field for describing the electrical wiring type if Other is selected. |
| `solar_panel_present` | `boolean` | Indicates whether solar panels are installed on the structure. |
| `solar_panel_type` | `string | null` | Specifies the type of solar panel system. `Photovoltaic``SolarThermal``Hybrid` |
| `solar_panel_type_other_description` | `string | null` | A free-form field to describe the solar panel system when Other is selected. |
| `smart_home_features` | `array | null` | List of smart home features installed in the property. |
| `smart_home_features_other_description` | `string | null` | Free-form description if any smart home features are not covered by the predefined list. |
| `hvac_unit_condition` | `string | null` | Visible exterior condition of the HVAC condensing unit, if present. `New``Good``Rusty``Leaking``Damaged` |
| `solar_inverter_visible` | `boolean` | Whether a solar inverter box is visible on exterior or utility closet. |
| `hvac_unit_issues` | `string | null` | Visual indicators of HVAC or external unit deterioration. `RustyUnit``LeakingPipes``MissingGrilles``ObstructedVent``WornFanHousing` |
| `hvac_installation_date` | `string | null` | Date HVAC equipment was installed/replaced (MEC). |
| `electrical_panel_installation_date` | `string | null` | Date main service panel was installed/upgraded (ELE). |
| `electrical_rewire_date` | `string | null` | Date of significant rewire (ELE). |
| `plumbing_system_installation_date` | `string | null` | Date supply/drain system was installed/replaced (PLU). |
| `water_heater_installation_date` | `string | null` | Date water heater was installed/replaced (PLU/BLD). |
| `solar_installation_date` | `string | null` | Date solar system was installed (SOL). |
| `solar_inverter_installation_date` | `string | null` | Date solar inverter was installed/replaced (SOL). |
| `well_installation_date` | `string | null` | Date well was installed (WEL/NRP). |
| `sewer_connection_date` | `string | null` | Date property connected to public sewer (LCU/LWS/PLU). |
| `water_connection_date` | `string | null` | Date property connected to public water (LCU/LWS/PLU). |
| `hvac_system_configuration` | `string | null` | HVAC configuration type. `SplitSystem``PackagedUnit``MiniSplit``HeatPumpSplit``VRF``Other` |
| `hvac_equipment_component` | `string | null` | HVAC component this record describes. `Condenser``AirHandler``CondenserAndAirHandler``PackageUnit``HeatPump``Other` |
| `hvac_capacity_kw` | `number | null` | Nameplate electrical capacity (kW) of the HVAC equipment. |
| `hvac_capacity_tons` | `number | null` | Cooling capacity in tons. |
| `hvac_seer_rating` | `number | null` | Seasonal Energy Efficiency Ratio (SEER). |
| `hvac_equipment_manufacturer` | `string | null` | Manufacturer of HVAC equipment. |
| `hvac_equipment_model` | `string | null` | Model number of HVAC equipment. |
| `water_heater_manufacturer` | `string | null` | Manufacturer of water heater. |
| `water_heater_model` | `string | null` | Model number of water heater. |
| `solar_inverter_manufacturer` | `string | null` | Manufacturer of solar inverter. |
| `solar_inverter_model` | `string | null` | Model number of solar inverter. |
## Provenance and coverage
A record of this class is validated against the same definition whatever jurisdiction it came from, which is what makes two counties comparable without a per-county adapter. A jurisdiction appears below only where a committed configuration serves this class's surface.
- Lee, Florida
- Palm Beach, Florida
- Miami-Dade, Florida
- Orange, Florida
- Santa Clara, California
How a new jurisdiction is brought online
---
# Delivery
# Delivery
The delivery platform: how software is built, assessed, deployed, published and kept compliant.
Two categories. Shipping is the pipeline — repository operations, the rule engine over infrastructure definitions, the build, the deployment, the compliance stage, and the orchestration that runs them in order. Distribution is what happens to the result: catalogues, environments, identity, metering and hosting.
Every stage has an API rather than a script, so a configuration bundle generated by a machine can be committed, assessed, built, deployed and published by the same calls a person would use.
- Access
- Assess
- Build
- Code
- Comply
- Console
- Deploy
- Environment
- Finance
- Health
- Host
- Marketplace
- Pipeline
- Setup
---
# Distribution
# Distribution
What happens to a build: catalogues, environments, identity, metering, hosting and self-service setup.
What happens to a build before somebody can call it?
Distribution covers everything between a built bundle and a running product in somebody's account. The catalogue publishes bundles and resolves what they depend on; environments are whole cloud accounts created, budgeted and destroyed over HTTP; identity issues the keys every call is authorised by; metering counts what was called, against the same identifier the endpoint definition already carries.
Two products here exist for cases the others do not cover. Hosting installs a vendor's own engine inside a customer's account for data that cannot leave it, and setup carries the fixed sequence that creates an account and its first environment as one step.
## Products
In the order the value chain runs.
1. Access has a recorded specification
1. Console has a recorded specification
1. Environment has a recorded specification
1. Finance has a recorded specification
1. Host has a recorded specification
1. Marketplace has a recorded specification
1. Setup has a recorded specification
---
# Access
# Access
Identity, single sign-on, API-key issuance and credential storage, with a stated boundary on who can reach a customer environment.
All product access control is by API key, and every environment has one. Access creates and manages the root identity that owns a company, the user identities belonging to its organisations, organisation parameters and credentials, the credentials a lender supplies for its own vendor accounts, and key rotation.
Rotating a key takes two factors: the organisation owner's identity and the current key.
## How it works
Storage is split by what is being stored. API keys are held encrypted; user identities and their credentials sit in the managed identity service rather than in any product's own database. User identity is two-factor.
No API access is held into a customer's environment, with Health as the single exception, and nobody reaches an environment through the console. The boundary is stated in the design notes rather than implied.
Temporary maintenance access is possible and costs four independent factors: the environment's API key, a user identity, an approval from the security officer, and an approval from the organisation's own owner. The route runs through Comply, which issues the credential after the environment owner approves the request by email.
Product dependencies are expected to sit in the same environment, so a call does not cross an environment boundary to authenticate. Four products are the stated exceptions, because they are the ones that operate on environments rather than inside one.
## Operations
### Account Partner Schema
`DELETE` `/`
#### Delete Partner Schema
`delete_partner_schema`
This service manages the deletion of a partner schema.
##### Request
application/json Copy .
```
{
"partner": "foopartner",
"product": "barproduct",
"schema": {
"price": 32,
"product_name": "apple"
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `partner`required | `string` | The name of the partner.Example `foopartner` |
| `product`required | `string` | The name of the product.Example `barproduct` |
##### Response `200``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `404``application/json`
1 fields
409 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
`POST` `/`
#### Create Partner Schema
`create_partner_schema`
This service manages the creation of a partner schema.
##### Request
application/json Copy .
```
{
"partner": "foopartner",
"product": "barproduct",
"schema": {
"price": 32,
"product_name": "apple"
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `partner`required | `string` | The name of the partner.Example `foopartner` |
| `product`required | `string` | The name of the product.Example `barproduct` |
| `schema`required | `object` | The JSON schema. |
##### Response `201``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `409``application/json`
1 fields
409 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
`PUT` `/`
#### Update Partner Schema
`update_partner_schema`
This service manages the update of a partner schema.
##### Request
application/json Copy .
```
{
"partner": "foopartner",
"product": "barproduct",
"schema": {
"price": 32,
"product_name": "apple"
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `partner`required | `string` | The name of the partner.Example `foopartner` |
| `product`required | `string` | The name of the product.Example `barproduct` |
| `schema`required | `object` | The JSON schema. |
##### Response `200``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
##### Response `404``application/json`
1 fields
409 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message with details. |
### Company Organization
`GET` `/`
#### Retrieve Company Organization List
`retrieve-company-organization-list`
This service retrieves company organization list.
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `company_name` | `string` query | `Amazon` | Company name |
| `organization_name` | `string` query | `Amazon Web Services` | Organization name |
##### Response `200``application/json`
1 fields
Successful Company Organization List Retrieve.
| Field | Type | Description |
| --- | --- | --- |
| `company_organization_list` | `object[]` | Company organization list |
| `organization_id` | `string` | Organization ID |
| `company_name` | `string` | Company name |
| `organization_name` | `string` | Organization name |
##### Other responses
`400``403`
`GET` `/{organization_id}`
#### Retrieve Company Organization
`retrieve-company-organization`
This service retrieves company organization.
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `organization_id` required | `string` path | `fxfxfxfx-fxfx-fxfx-fxfx-fxfxfxfxfxfx` | Organization ID |
##### Response `200``application/json`
1 fields
Successful Company Organization Retrieve.
| Field | Type | Description |
| --- | --- | --- |
| `company_organization` | `object` | Company organization object |
| `organization_id` | `string` | Organization ID |
| `company_name` | `string` | Company name |
| `organization_name` | `string` | Organization name |
##### Other responses
`400``403``404`
### Access Invitations
`POST` `/{application_name}/invitations`
#### Invite User
`inviteUser`
Invites a new user.
Invitation will redirect user to the provided URL on acceptance. Upon acceptance, the user will be redirected to the provided URL with a fragment parameters:
`staircase_product=Access` `action=ACCEPT_INVITATION` and `result` containing on of the following values:
- `ACCEPTED`,- User accepted the invitation
- `BAD_REQUEST`,- Bad request, one of the required parameters is missing
- `UNKNOWN_ERROR`,- Unknown error occurred
- `INVITATION_NOT_FOUND`,- Invitation not found. Could be expired or invalid code
- `INVITATION_NOT_VALID`,- Invitation not valid. Could be already accepted or expired
- `INTERNAL_SERVER_ERROR`,- Internal server error occurred
The invitation URL will be valid for 1 month.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com",
"redirect_url": "https://webhook.site/d9b8f770-38c2-4584-8944-0b7194d203e8?guid=123"
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK Response
```
[
{
"email": "johndoe@email.com",
"invitation_url": "https://cerf-dev.staircaseapi.com/access/invitation-accept?code=c6d0b273-5dd1-4819-9dd0-00e109a31723&redirect_url=https%3A//webhook.site/d9b8f770-38c2-4584-8944-0b7194d203e8%3Fguid%3D123"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `redirect_url` | `string` | URL to redirect user on invitation acceptance.Example `https://webhook.site/d9b8f770-38c2-4584-8944-0b7194d203e8?guid=123` |
##### Response `201``application/json`
2 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `invitation_url` | `string` | URL to confirm the invitation.Example `https://cerf-dev.staircaseapi.com/access/invitation-accept?code=c6d0b273-5dd1-4819-9dd0-00e109a31723&redirect_url=https%3A//webhook.site/d9b8f770-38c2-4584-8944-0b7194d203e8%3Fguid%3D123` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `409``application/json`
1 fields
Email already registered
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`404`
### Access Authorization
`POST` `/{application_name}/login`
#### Access login
`getUserToken`
Access login enables you to use your credentials to retrieve a valid access_token, id_token, token_type, refresh_token. X-API-KEY is not required for this endpoint.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com",
"password": ""
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"refresh_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"id_token": "",
"access_token": "",
"token_type": "Bearer",
"expires_in": "86400"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `password` | `string (password)` | User password.Example `` |
##### Response `200``application/json`
5 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `refresh_token` | `string` | The refresh token.Example `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `id_token` | `string` | Temporary id token obtained.Example `` |
| `access_token` | `string` | Temporary access token obtained.Example `` |
| `token_type` | `string` | The token type.Example `Bearer` |
| `expires_in` | `string` | The expiration period of the authentication result in seconds.Example `Bearer ` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`POST` `/{application_name}/resend-activation`
#### Resend activation email
`resendActivation`
This endpoint enables you to resend email to activate your account in case you didn't receive it from the first time. X-API-KEY is not required for this endpoint.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com"
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "Activation email is resented"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Resented successfully.Example `Activation email is resented` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User already confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`POST` `/{application_name}/change-password`
#### Change password
`changePassword`
Change user password using access token. Access token can be received by this endpoint Access Login. Important Note, this endpoint does not work with SSO users.
X-API-KEY is not required for this endpoint.
##### Request
application/json Copy
```
{
"old_password": "164f8UY=oj!",
"new_password": "154fFV0=091"
}
```
##### Response
201400 application/json400 text/html
application/json Copy Password changed
```
[
{
"message": "Password has been successfully changed"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `Authorization` required | `string` header | `` | Authorization token, obtained login service. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `old_password` | `string` | Current user password.Example `164f8UY=oj!` |
| `new_password` | `string` | New user password.Example `164f8UY=oj!` |
##### Response `201``application/json`
1 fields
Password changed
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Password changedExample `Password has been successfully changed` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`POST` `/{application_name}/sign-out`
#### Sign out
`signOut`
Proceed user sign out using access token. Access token can be received by this endpoint Access Login. X-API-KEY is not required for this endpoint.
##### Response
201400 application/json400 text/html
application/json Copy Sign out
```
[
{
"message": "Sign out succeeded"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `Authorization` required | `string` header | `` | Authorization token, obtained login service. |
##### Response `201``application/json`
1 fields
Sign out
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Password changedExample `Sign out succeeded` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`GET` `/{application_name}/sign-out-by-cookie`
#### Sign out by cookie
`signOutByCookie`
This endpoint is meant to be visited by the user directly and should not be used with XHR requests. When accessed properly, the user will be correctly redirected, and all their tokens will be invalidated. This endpoint allows users to sign out using their access token stored in cookies.
Access Token Cookie: __sc.acact ID Token Cookie: __sc.acidt
Important Notes
Do Not Use with XHR Requests: This endpoint is designed for direct user interaction and should not be accessed through XHR requests. Token Invalidation: Upon successful logout, all user tokens will be invalidated. Redirection: If the logout is successful, the user will be redirected to the specified logout_uri. If the logout fails, the user will be redirected to the redirected_uri.
Usage
Ensure Cookies Are Set: The following cookies must be present: __sc.acact (Access Token) __sc.acidt (ID Token) Access Token: Can be received from the Access Login endpoint. No X-API-KEY Required: This endpoint does not require the X-API-KEY header.
##### Response
302400 application/json400 text/html
application/json Copy Sign out
```
[
{
"message": "Sign out succeeded"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
##### Response `302``application/json`
1 fields
Sign out
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Password changedExample `Sign out succeeded` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`POST` `/{application_name}/forgot-password`
#### Forgot password
`forgotPassword`
Forgot password endpoint sends link on user's email address to reset password. Important Note, this endpoint does not work with SSO users.
X-API-KEY is not required for this endpoint.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com"
}
```
##### Response
202400 application/json400 text/html
application/json Copy Forgot password
```
[
{
"message": "Email sent"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
##### Response `202``application/json`
1 fields
Forgot password
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Password changedExample `Email sent` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
1 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`404`
`POST` `/{application_name}/confirm-code`
#### Confirm forgot password
`confirmForgotPassword`
Confirm forgot password endpoint change user password using confirmation code retrieved by Forgot password. Important Note, this endpoint does not work with SSO users.
X-API-KEY is not required for this endpoint.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com",
"confirmation_code": "255252",
"new_password": "P@ssword"
}
```
##### Response
200400 application/json400 text/html
application/json Copy Confirm forgot password
```
[
{
"message": "Password changed"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `confirmation_code` | `string` | Code retrieved by email.Example `255252` |
| `new_password` | `string` | New user password.Example `P@ssword` |
##### Response `200``application/json`
1 fields
Confirm forgot password
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Password changedExample `Password changed` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
1 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`404`
`POST` `/{application_name}/refresh-token`
#### Refresh Token
`refreshToken`
Refresh Token allows you to refresh access token. X-API-KEY is not required for this endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"id_token": "",
"access_token": "",
"token_type": "Bearer",
"expires_in": "86400"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `Authorization` required | `string` header | `` | Refresh token, obtained by login service. |
##### Response `200``application/json`
4 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `id_token` | `string` | Temporary id token obtained.Example `` |
| `access_token` | `string` | Temporary access token obtained.Example `` |
| `token_type` | `string` | The token type.Example `Bearer` |
| `expires_in` | `string` | The expiration period of the authentication result in seconds.Example `Bearer ` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`POST` `/{application_name}/validate-token`
#### Validate Access Token
`validateAccessToken`
Validate Access Token endpoint. X-API-KEY is not required for this endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
{
"message": "Token is valid"
}
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `Authorization` required | `string` header | `` | Access token, obtained by login service. |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message.Example `Token is valid` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
### Access User
`POST` `/{application_name}/users`
#### Create User
`createUser`
Creates a new user. X-API-KEY is not required for this endpoint.
This endpoint will create a new user and send a confirmation email to the user.
Before creating a new user, user can be invited using the invitation endpoint. If invitation was accepted, the user will be created and confirmed automatically.
##### Request
application/json Copy
```
{
"email": "johndoe@email.com",
"password": ""
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK Response
```
[
{
"id": "978412689485",
"email": "johndoe@email.com",
"status": "CONFIRMED"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `password` | `string (password)` | Password for the new user.Example `` |
##### Response `201``application/json`
3 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | User id.Example `64564689894561` |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `status` | `string` | Status of the user CONFIRMED or UNCONFIRMED.`CONFIRMED``UNCONFIRMED`Example `CONFIRMED` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
Email already registered
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/users`
#### List users
`listUserInfo`
List Users Info
List users information by email. In case query parameter has some special characters such '+' or '/' it must be encoded. X-API-KEY is not required for this endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK Response
```
[
{
"users": [
{
"id": "f5fa64a9-51b6-41c3-b22e-fd8d7b1dadb2",
"email": "example@email.com",
"user_creation_date": "2023-10-13T11:32:06.637000+00:00",
"user_last_modified_date": "2023-10-13T11:57:36.835000+00:00",
"person_identifier": "01H84EDXPD3PBH21DGDQFZP06Y",
"company_identifier": "01HCHKS73ME9A9W7XGDTX9Z9PC",
"status": "CONFIRMED"
}
],
"next_token": null
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `email` | `string (email)` query | `example@email.com` | User email to query. |
| `next_token` | `string` query | `CAISqQIIARKCAggDEv0BAAzZDJsxrI3ydVKVDZyI4WtUDKZt1d0R6fu+3POnqFCKeyJAbiI6IlBhZ2luYXRpb25Db250aW51YXRpb25EVE8iLCJuZXh0S2V5IjoiQUFBQUFBQUFBcnhoQVFFQmNFZEVNcVZrUzFDV1ZtWTlyYjM4NEsxM0VnY2psRW5VdXhNL3hqbFR0dHRsYm1ZN05qSm1aV1ZoWm1ZdE0yUXdNUzAwTTJOa0xXSTBabVV0WlRoa04yRTFPRFF3TXpkbE93PT0iLCJwYWdpbmF0aW9uRGVwdGgiOjI1LCJwcmV2aW91c1JlcXVlc3RUaW1lIjoxNjk4MjE5OTIxNDE2fRogIRzi3AAH44NsO9VRPe6wxirYfEjiup4H6OAJ2P6ULL8=` | next_token. |
##### Response `200``application/json`
2 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `users` | `object[]` | Users data. |
| `id` | `string` | User id.Example `64564689894561` |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `user_creation_date` | `string` | User creation date.Example `2023-10-13T11:32:06.637000+00:00` |
| `user_last_modified_date` | `string` | User last modified date.Example `2023-10-13T11:32:06.637000+00:00` |
| `person_identifier` | `string` | Staircase global person ID.Example `01GYCBKPSMTJYJR1PG9JS37FTE` |
| `company_identifier` | `string` | Staircase global company ID.Example `01GYCBKPSMTJYJR1PG9JS37FTE` |
| `status` | `string` | Status of the user.Example `CONFIRMED` |
| `next_token` | `string` | next_token. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/{application_name}/users/{user_id}`
#### Get User
`getUser`
Get user endpoint. X-API-KEY is not required for this endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK Response
```
[
{
"id": "978412689485",
"email": "johndoe@email.com",
"person_identifier": "01GYCBKPSMTJYJR1PG9JS37FTE",
"company_identifier": null,
"status": "CONFIRMED"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name. |
| `user_id` required | `string` path | `856451298456123` | User id to query. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Response `200``application/json`
5 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | User id.Example `64564689894561` |
| `email` | `string (email)` | Email of the user.Example `johndoe@email.com` |
| `person_identifier` | `string` | Staircase global person ID.Example `01GYCBKPSMTJYJR1PG9JS37FTE` |
| `company_identifier` | `string` | Staircase global company ID.Example `01GYCBKPSMTJYJR1PG9JS37FTE` |
| `status` | `string` | Status of the user.Example `CONFIRMED` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`GET` `/user-info`
#### Get User Info
`getUserInfo`
Get user information using access token. Access token can be received by this endpoint Access Login. X-API-KEY is not required for this endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK Response
```
[
{
"communications": [
{
"@id": "01GZP2AQ2JKPZXSXMJ1CA4TD3N",
"@type": "person",
"domain_name": "email.co",
"website": "staircase.co"
},
{
"@id": "01GZP2AQ2JKPZXSXMJ1CA4TD3N",
"@type": "person",
"email_address": "email@example.com"
}
],
"companies": [
{
"@id": "01H1XQHK0WWMX23XDX1GX3MCKR",
"@type": "company",
"company_identifier": "27374737",
"has_communication_method": "01GZP2AQ2JKPZXSXMJ1CA4TD3N",
"name": "Staircase Company"
}
],
"people": [
{
"@id": "01GZP2AQ2JKPZXSXMJ1CA4TD3N",
"@type": "person",
"has_communication_method": "01GZP2AQ2JKPZXSXMJ1CA4TD3N",
"person_identifier": "112557303379029896330"
}
]
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained by login service. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`200``204``401``404`
### Access Applications
`GET` `/applications`
#### List applications
`listApplications`
List Applications
List applications endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK Response
```
{
"result": [
{
"application_name": "test-user-pool-client-comply",
"redirect_uri": "https://test.test.com/access/callback",
"logout_uri": "https://test.test.com/access/callback"
}
]
}
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Response `200``application/json`
1 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `result` | `object[]` | Array of applications |
| `application_name` | `string` | Application name.Example `access` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
1 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Application not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`POST` `/applications`
#### Create application
`createApplication`
Create Application
Creates a new application.
##### Request
application/json Copy
```
{
"application_name": "access",
"redirect_uri": "https://test.test.com/access/callback"
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK Response
```
[
{
"message": "Application access created successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `application_name`required | `string` | Application name.Example `access` |
| `redirect_uri`required | `string` | Redirect_uri.Example `https://test.test.com/access/callback` |
| `logout_uri` | `string` | Logout_uri.Example `https://test.test.com/access/callback` |
##### Response `201``application/json`
1 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message.Example `Application access created successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`PUT` `/applications/{application_name}`
#### Update application
`updateApplication`
Update Application
Updates existing application.
##### Request
application/json Copy
```
{
"application_name": "access",
"redirect_uri": "https://test.test.com/access/callback"
}
```
##### Response
201400 application/json400 text/html404
application/json Copy OK Response
```
[
{
"message": "Application access updated successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy App not found
```
[
{
"error": "Application access not found"
}
]
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name to delete. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `redirect_uri`required | `string` | Redirect_uri.Example `https://test.test.com/access/callback` |
| `logout_uri` | `string` | Logout_uri.Example `https://test.test.com/access/callback` |
##### Response `201``application/json`
1 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message.Example `Application access created successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
App not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/applications/{application_name}`
#### Get Application
`getApplication`
Get application endpoint.
##### Response
200400 application/json400 text/html
application/json Copy OK Response
```
[
{
"application_name": "access",
"redirect_uri": "https://test.test.com/access/callback",
"logout_uri": "https://test.test.com/access/callback"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name to get. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Response `200``application/json`
3 fields
OK Response
| Field | Type | Description |
| --- | --- | --- |
| `application_name` | `string` | Application name.Example `access` |
| `redirect_uri` | `string` | Redirect_uri.Example `https://test.test.com/access/callback` |
| `logout_uri` | `string` | Logout_uri.Example `https://test.test.com/access/callback` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Application not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`DELETE` `/applications/{application_name}`
#### Delete Application
`deleteApplication`
Delete application endpoint.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `application_name` required | `string` path | `access` | Application name to delete. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Application not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`204`
### Authorization
`POST` `/authorize`
#### Authorization
`authorization`
Makes an authorization decision about a service request described in the parameters. The decision is based on the policies stored in the policy store.
##### Request
application/json Copy
```
{
"policy_store_id": "DxK7hSQRzYWoCGSeumNvm",
"principal": {
"entityType": "ExampleCo::Loan::Borrower",
"entityId": "Steve"
},
"action": {
"actionType": "ExampleCo::Loan::Action",
"actionId": "GetListingInfo"
},
"resource": {
"entityType": "ExampleCo::Loan::Listing",
"entityId": "12345"
}
}
```
##### Response
200400404
application/json Copy Successfully authorized.
```
{
"decision": "ALLOW",
"determining_policies": [
{
"policyId": "WVKdXE7dNDJNRXYVAdCJmd"
}
],
"errors": []
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `policy_store_id`required | `string` | ID of the policy store.Example `Dc3v9eLa2UbfCrw6wrkcmK` |
| `principal` | `object` | Principal of the policy. |
| `entityType`required | `string` | Entity type of the principal.Example `loan::borrower` |
| `entityId`required | `string` | Entity ID of the principal.Example `john` |
| `action` | `object` | Action of the policy. |
| `actionType`required | `string` | Type of the action.Example `loan::Action` |
| `actionId`required | `string` | ID of the action.Example `GetListingInfo` |
| `resource` | `object` | Resource of the policy. |
| `entityType`required | `string` | Entity type of the resource.Example `loan::preapprovallist` |
| `entityId`required | `string` | Entity ID of the resource.Example `johnlist` |
##### Response `200``application/json`
3 fields
Successfully authorized.
| Field | Type | Description |
| --- | --- | --- |
| `decision`required | `string` | Decision of the authorization.`ALLOW``DENY` |
| `determining_policies`required | `object[]` | The list of determining policies used to make the authorization decision. |
| `errors`required | `string[]` | Errors that occurred while making an authorization decision. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Site Logs Configurations
`POST` `/configurations`
#### Save Configuration
`saveConfiguration`
##### Request
application/json Copy
```
{
"configuration_id": "8237fc96-0d4a-484c-b2e3-ffd0f800eae1"
}
```
##### Response
200400404
application/json Copy Success response
```
{
"foo": "bar"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `configuration_id`required | `string` | Simple Site Configuration IDExample `8237fc96-0d4a-484c-b2e3-ffd0f800eae1` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`200`
`GET` `/configurations`
#### List Configurations
`listConfigurations`
##### Response
200400404
application/json Copy List Configurations
```
{
"domain_name": "abc.cloudfront.net",
"configuration_id": "8237fc96-0d4a-484c-xx-xxx",
"distribution_id": "E23M6IP4FJ0xxxx"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Response `200``application/json`
3 fields
List Configurations
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Domain NameExample `foo` |
| `configuration_id` | `string` | Configuration IDExample `configuration-id` |
| `distribution_id` | `string` | Distribution IDExample `distribution-id` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Account configurations
`POST` `/create-configurations`
#### Create Configurations
`store_new_environment_configurations`
Configurations are used to change a product behavior for one or multiple customers' accounts, this will enable Staircase default configurations, and the customer can change as needed in his account.
The account data bundle enables the customer environment with Staircase default configurations for products like Suite.
Example of configurations:
- Allow multiple registration = true|false
- Borrower flow enabled = true|false
- Data manager flow enabled = true|false
##### Request
Example configurationExample without environment
application/json Copy .
```
{
"environment": "account.staircaseapi.com",
"product": "myProduct",
"configurations": [
{
"key": "server_domain",
"value": "myserver.com"
},
{
"key": "server_key",
"value": "fxfxfxfxfxfx"
}
]
}
```
application/json Copy .
```
{
"product": "myProduct",
"configurations": [
{
"key": "server_domain",
"value": "myserver.com"
},
{
"key": "server_key",
"value": "fxfxfxfxfxfx"
}
]
}
```
##### Response
201400409500
application/json Copy 201 response.
```
{
"message": "Configurations were created successfully."
}
```
application/json Copy 400 response.
```
{
"message": "Invalid body JSON."
}
```
application/json Copy 409 response.
```
{
"message": "This resource was already previously created. Please, use the update endpoint."
}
```
application/json Copy 500 response.
```
{
"message": "Internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `environment` | `string` | The environment hosts.Example `account.staircaseapi.com` |
| `product`required | `string` | The product to be configured.Example `newProduct` |
| `configurations` | `object[]` | The product configurations. |
| `key` | `string` | Key |
| `value` | `string` | Key |
##### Response `201``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configurations were created successfully. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Invalid body JSON. |
##### Response `409``application/json`
1 fields
409 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The resource was already previously created. |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`GET` `/retrieve-configurations`
#### Retrieve Configurations
`retrieve_configurations`
This service retrieves configurations from a product and/or environment. If no query string parameters are passed then the response should contain configurations that have been registered. Configurations from master environment registered will be retrieved as well, all global and local credentials for the given inputs.
##### Response
200400404500
application/json Copy 200 response.
```
[
{
"environment": "account.staircaseapi.com",
"product": "myProduct",
"is_local": true,
"created_at": "2011-10-05T14:48:00.000",
"updated_at": "2011-10-05T14:48:00.000",
"created_by_environment": "account.staircaseapi.com",
"configurations": [
{
"key": "server_domain",
"value": "myserver.com"
},
{
"key": "server_key",
"value": "fxfxfxfxfxfx"
}
]
},
{
"environment": "test.staircaseapi.com",
"product": "myProduct",
"is_local": false,
"created_at": "2011-10-05T14:48:00.000",
"updated_at": "2011-10-05T14:48:00.000",
"created_by_environment": "test.staircaseapi.com",
"configurations": [
{
"key": "ttl",
"value": 20
}
]
}
]
```
application/json Copy 400 response.
```
{
"message": "\"Invalid json body.\""
}
```
application/json Copy 404 response.
```
{
"message": "No one configurations were found."
}
```
application/json Copy 500 response.
```
{
"message": "Internal server error"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
| `environment` | `string` query | `account.staircaseapi.com` | The environment host, configurations without environment will be retrieved if this filter is not input. |
| `product` | `string` query | `newService` | Product to retrieve configurations. |
##### Response `200``application/json`
7 fields
200 response.
| Field | Type | Description |
| --- | --- | --- |
| `environment` | `string` | The environment hosts.Example `account.staircaseapi.com` |
| `product` | `string` | The product to be configured.Example `newProduct` |
| `created_at` | `string` | Date that it was created.Example `2011-10-05T14:48:00.000` |
| `updated_at` | `string` | Date that it was updated.Example `2011-10-05T14:48:00.000` |
| `created_by_environment` | `string` | Name of environment responsible to create it.Example `2011-10-05T14:48:00.000` |
| `is_local` | `boolean` | Indicates if the configuration was created by the local environment.Example `true` |
| `configurations` | `object[]` | The product configurations. |
| `key` | `string` | — |
| `value` | `—` | — |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `404``application/json`
1 fields
404 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`PUT` `/update-configurations`
#### Update Configurations
`update_environment_configurations`
This service update product configurations. Configurations are used to change a product behavior.
##### Request
Example configurationExample without environment
application/json Copy .
```
{
"environment": "account.staircaseapi.com",
"product": "myProduct",
"configurations": [
{
"key": "server_domain",
"value": "myserver.com"
},
{
"key": "server_key",
"value": "fxfxfxfxfxfx"
}
]
}
```
application/json Copy .
```
{
"product": "myProduct",
"configurations": [
{
"key": "server_domain",
"value": "myserver.com"
},
{
"key": "server_key",
"value": "fxfxfxfxfxfx"
}
]
}
```
##### Response
201400404500
application/json Copy 201 response.
```
{
"message": "Configurations were updated successfully."
}
```
application/json Copy 400 response.
```
{
"message": "Invalid body JSON."
}
```
application/json Copy 404 response.
```
{
"message": "No one local resource was found."
}
```
application/json Copy 500 response.
```
{
"message": "Internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `environment` | `string` | The environment hosts.Example `account.staircaseapi.com` |
| `product`required | `string` | The product to be configured.Example `newProduct` |
| `configurations` | `object[]` | The product configurations. |
| `key` | `string` | Key |
| `value` | `string` | Value |
##### Response `201``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configurations were updated successfully. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Invalid body JSON. |
##### Response `404``application/json`
1 fields
404 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`DELETE` `/delete-configurations`
#### Delete Configurations
`delete_environment_configurations`
This service delete product configurations. Configurations are used to change a product behavior.
##### Response
200400404500
application/json Copy 201 response.
```
{
"message": "Configurations were deleted successfully."
}
```
application/json Copy 400 response.
```
{
"message": "Invalid body JSON."
}
```
application/json Copy 404 response.
```
{
"message": "No one configurations were found."
}
```
application/json Copy 500 response
```
{
"message": "Internal server error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `product` required | `string` query | `myProduct` | Product |
| `environment` | `string` query | `account.staircaseapi.com` | Product |
##### Response `200``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configurations were deleted successfully. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Invalid body JSON. |
##### Response `404``application/json`
1 fields
404 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `500``application/json`
1 fields
500 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
### Customer
`POST` `/create-customer`
#### Create Customer
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Content-Type` required | `string` header | `application/json` | Content Type |
`GET` `/retrieve-customer`
#### Retrieve Customer
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Content-Type` required | `string` header | `application/json` | Content Type |
| `customer_id` | `string` query | `ba4e8f60-f259-11eb-9a03-0242ac130003` | — |
| `email` | `string` query | `customer@domain.com` | — |
### Account Partner
`POST` `/credentials`
#### Register Credentials
`store_new_environment_credentials`
This service manages data Partner Account credentials. Data partner credentials enable Staircase Mortgage products to securely connect with specific data partners. They authorize Staircase to send data partners requests and receive their responses, both of which are persisted in the customer’s dedicated account.
The Account data bundle automatically registers the Marketplace environment which includes all needed configurations and credentials to start using Staircase products in the customer environment.
##### Request
application/json Copy .
```
{
"environment": "account.staircaseapi.com",
"partner": "atomic",
"type": "production",
"credentials": {
"login": "username",
"password": "myPass"
}
}
```
##### Response
201400
application/json Copy 201 response.
```
{
"message": "Credentials are encrypted and stored successfully."
}
```
application/json Copy 400 response.
```
{
"message": "error in creating Credentials credentials is a required field and it must be an array"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `environment` | `string` | The environment hostExample `account.staircaseapi.com` |
| `partner`required | `string` | Partner Account.Example `newService` |
| `product` | `string` | Product account.Example `newProduct` |
| `credentials`required | `object` | Partner that the credentials is used |
| `type` | `string` | Type can be production, test or empty`production``test`Example `production` |
##### Response `201``application/json`
1 fields
201 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Credentials are encrypted and stored successfully. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error in creating credentials. |
`POST` `/upload-certificate/{partner}`
#### Upload Certificate
`upload_partner_certificate`
This service is used to generate a pre-signed URL to upload the partner certificate to Staircase cloud environment. The certificate will be securely stored and can be retrieved by the /retrieve-certificate endpoint
Note: This will NOT upload your certificate.
To upload the certificate file, you will need to issue a PUT request to the URL returned by the response body. See example, code snippet below:
```
# Upload Certificate to the presigned url
import requests
# For example, the presigned_url might look like this:
upload_presigned_url = ""
# Set the path to the file you want to upload
filepath = "certificate.pfx"
# Set the headers appropriately
headers = {
'Content-Type': 'application/x-pkcs12'
}
# Read the file data and make the PUT request
with open(filepath, 'rb') as file:
payload = file.read
response = requests.put(url=upload_presigned_url, headers=headers, data=payload)
```
##### Request
application/json Copy .
```
{
"host": "account.staircaseapi.com"
}
```
##### Response
200400500
application/json Copy 200 response
```
{
"message": "Pre-signed url successfully generated",
"host": "my_partner_host",
"type": "production",
"presigned_url": "https://my_partner-certificate-bucket.s3.amazonaws.com/"
}
```
application/json Copy 400 response
```
{
"message": "host must exist in body"
}
```
application/json Copy 500 response
```
{
"message": "Internal server error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
| `partner` required | `string` path | `my_partner_name` | Partner Account. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `host`required | `string` | The environment hostExample `account.staircaseapi.com` |
##### Response `200``application/json`
3 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Pre-signed URL successfully generated. |
| `host` | `string` | host |
| `presigned_url` | `string` | Pre-signed URL to upload file. |
##### Response `400``application/json`
1 fields
400 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request. |
##### Response `500``application/json`
1 fields
500 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`PUT` `/credentials`
#### Update Credentials
`update_new_environment_credentials`
This service updates existing data partner credentials. The password provided when creating the credentials must be supplied in the request body when calling this service.
##### Request
application/json Copy .
```
{
"environment": "account.staircaseapi.com",
"partner": "atomic",
"product": "myProduct",
"type": "production",
"credentials": {
"login": "username",
"password": ""
}
}
```
##### Response
200400404
application/json Copy 200 response.
```
{
"message": "Credentials are encrypted and updated successfully"
}
```
application/json Copy 400 response.
```
{
"message": "error in creating Credentials credentials is a required field and it must be an array"
}
```
application/json Copy 404 response.
```
{
"message": "Credentials Not Found."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `environment` | `string` | The environment hostExample `account.staircaseapi.com` |
| `partner`required | `string` | Partner that the credentials is usedExample `newService` |
| `product` | `string` | Product account credentials.Example `newProduct` |
| `credentials`required | `object` | Partner that the credentials is used |
##### Response `200``application/json`
1 fields
200 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Credentials are encrypted and updated successfully. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `404``application/json`
1 fields
404 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`GET` `/retrieve-certificate/{partner}`
#### Retrieve Certificate
`retrieve_partner_certificate`
This service is used to generate a pre-signed URL to download the partner certificate from Staircase cloud environment. The certificate is securely stored and can be uploaded by the /upload-certificate endpoint
##### Response
200400404500
application/json Copy 200 response
```
{
"message": "Pre-signed URL successfully generated",
"presigned_url": "https://bucket.s3.amazonaws.com/my_partner/my_partner_host.pfx?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=111111"
}
```
application/json Copy 400 response
```
{
"message": "The partner path must exist. Please use /{partner}?host={host}"
}
```
application/json Copy 404 response
```
{
"message": "Certificate not found."
}
```
application/json Copy 500 response
```
{
"message": "Internal server error"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `partner` required | `string` path | `my_partner_name` | Partner Account. |
| `host` required | `string` query | `my_partner_host` | The host of the partner that was used to upload the certificate. |
| `should_use_only_local_env` | `boolean` query | `true` | Define if it should only retrieve certificate from local environment and not master environment. (in any case, local environment has preference) |
##### Response `200``application/json`
3 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message. |
| `presigned_url` | `string` | The pre-signed URL used to retrieve the partner host certificate. |
| `is_certificate_from_local_env` | `boolean` | Informs if the pre-signed URL was retrieved from local environment or master environment. |
##### Response `400``application/json`
1 fields
400 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request. |
##### Response `404``application/json`
1 fields
404 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Certificate not found. |
##### Response `500``application/json`
1 fields
500 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
`DELETE` `/credentials`
#### Delete Credentials
`delete-delete-credentials`
This service deletes all data partner and credentials that have been created for a specific environment or product locally.
##### Response
200400403404
application/json Copy 200 response
```
{
"message": "Credentials are encrypted and stored successfully."
}
```
application/json Copy 400 response
```
{
"message": "f\"error in retrieving Credentials environment is a required field in the queryString\""
}
```
application/json Copy 403 response
```
{
"message": "error in retrieving Credentials Wrong Password"
}
```
application/json Copy 404 response
```
{
"message": "Not Found"
}
```
##### Parameters
7
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
| `environment` | `string` query | `account.staircaseapi.com` | Environment |
| `product` | `string` query | `newService` | Product to retrieve credentials. |
| `partner` required | `string` query | `newService` | Partner Account. |
| `type` | `string` query | `production` | Type can be production, test or empty |
| `password` | `string` query | `` | Password used to encrypt the Credentials |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The message. |
##### Response `400``application/json`
1 fields
400 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `403``application/json`
1 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `404``application/json`
1 fields
404 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
### Account Customer
`POST` `/customer-accounts`
#### Create Customer Account
`post-customer-accounts`
Create Customer Account creates your account in Staircase. After successful account creation, an email containing an API key is sent to the email address you provided. Company Organizations:
Organizations help you group your accounts and environments, as you grow and scale with Staircase. Define a Company organization by going to the Add Company Organization service, after is created you can retrieve the company organization.
To obtain access to Staircase APIs in the documentation environment "api.staircase.co", activate your API Key in this link. Use your activated API Key to send requests to any product in the documentation.
##### Request
Create AccountCreate Account with Organization
application/json Copy Creates a customer account with required fields
```
{
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"company_name": "DoeINC"
}
```
application/json Copy Creates a customer account with organization ID instead of Company Name
```
{
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"organization_id": "fxfxfxfx-fxfx-fxfx-fxfx-fxfxfxfxfxfx"
}
```
##### Response
application/json Copy Account creation successful.
```
{
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"company_name": "DoeINC"
}
```
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name`required | `string` | Customer first nameExample `Alan` |
| `last_name`required | `string` | Customer last nameExample `Turing` |
| `email`required | `string` | Customer email addressExample `Alan.Turing@example.com` |
| `company_name`required | `string` | Public company nameExample `TuringINC` |
| `organization_id` | `string` | Organization IDExample `fxfxfxfx-fxfxfx-fxfxfx-fxfxfxfx` |
| `callback_url` | `string` | URL address used to redirect the user to a webpage once its click on the confirmation button inside the welcome email. The confirmation_token used to confirm the email will be added on the query parameters in this URL.Example `https://mydomain.com` |
##### Response `201``application/json`
6 fields
Account creation successful.
| Field | Type | Description |
| --- | --- | --- |
| `account_id`required | `string` | Account IDExample `f2ee7908-daee-4da0-9cbe-f8dbcb9dab53` |
| `first_name`required | `string` | Customer first nameExample `Alan` |
| `last_name`required | `string` | Customer last nameExample `Turing` |
| `email`required | `string` | Customer email addressExample `Alan.Turing@example.com` |
| `company_name`required | `string` | Public company nameExample `TuringINC` |
| `organization_id` | `string` | Organization IDExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
##### Other responses
`400``500`
`PUT` `/customer-accounts`
#### Update Customer Account
`put-customer-accounts`
Update Customer Account updates your account in Staircase. An organization can be added to the user by updating the organization_id field.
##### Request
ExampleExample2
application/json Copy Updates a customer account
```
{
"account_key": "92e23b69-643c-453c-811d-ec2bc20a35e0",
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"company_name": "DoeINC"
}
```
application/json Copy Updates a customer account with organization ID instead of Company Name
```
{
"account_key": "92e23b69-643c-453c-811d-ec2bc20a35e0",
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"organization_id": "fxfxfxfx-fxfx-fxfx-fxfx-fxfxfxfxfxfx"
}
```
##### Response
application/json Copy Account creation successful.
```
{
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"company_name": "DoeINC"
}
```
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `account_key`required | `string` | API key associated to the userExample `92e23b69-643c-453c-811d-ec2bc20a35e0` |
| `first_name` | `string` | Customer first nameExample `Alan` |
| `last_name` | `string` | Customer last nameExample `Turing` |
| `email` | `string` | Customer email addressExample `Alan.Turing@example.com` |
| `company_name` | `string` | Public company nameExample `TuringINC` |
| `organization_id` | `string` | Organization IDExample `fxfxfxfx-fxfxfx-fxfxfx-fxfxfxfx` |
##### Response `200``application/json`
6 fields
Account creation successful.
| Field | Type | Description |
| --- | --- | --- |
| `account_id`required | `string` | Account IDExample `f2ee7908-daee-4da0-9cbe-f8dbcb9dab53` |
| `first_name`required | `string` | Customer first nameExample `Alan` |
| `last_name`required | `string` | Customer last nameExample `Turing` |
| `email`required | `string` | Customer email addressExample `Alan.Turing@example.com` |
| `company_name`required | `string` | Public company nameExample `TuringINC` |
| `organization_id` | `string` | Organization IDExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
##### Other responses
`400`
`GET` `/organization-account`
#### Retrieve Organization Account List
`get-retrieve-organization-account-list`
This service retrieves a list of customer accounts associated with a Company organization, organizations are defined in the Company product.
Company Organizations:
Organizations help you group your accounts and environments, as you grow and scale with Staircase. Define a Company organization by going to the Add Company Organization service, after is created you can retrieve the company organization in this service.
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
| `organization_id` required | `string` query | `fxfxfxfx-fxfx-fxfx-fxfx-fxfxfxfxfx` | The organization ID. |
##### Response `200``application/json`
6 fields
Account retrieved successful.
| Field | Type | Description |
| --- | --- | --- |
| `account_id`required | `string` | Account IDExample `f2ee7908-daee-4da0-9cbe-f8dbcb9dab53` |
| `account_key`required | `string` | Account KeyExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
| `organization_id`required | `string` | Organization IDExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
| `first_name`required | `string` | Customer first nameExample `Alan` |
| `last_name`required | `string` | Customer last nameExample `Turing` |
| `email`required | `string` | Customer email addressExample `Alan.Turing@example.com` |
##### Other responses
`400``401`
`POST` `/organization-account`
#### Create Organization Account
`post-create-organization-account`
Create Organization Account creates organization account in Staircase.
##### Request
application/json Copy Create using required fields
```
{
"organization_id": "fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx"
}
```
##### Response
application/json Copy Account creation successful.
```
{
"first_name": "Vlad",
"last_name": "Doe",
"email": "vlad@example.com",
"company_name": "DoeINC"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `organization_id`required | `string` | Organization IDExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
| `first_name` | `string` | Customer first nameExample `Alan` |
| `last_name` | `string` | Customer last nameExample `Turing` |
| `email` | `string` | Customer email addressExample `Alan.Turing@example.com` |
##### Response `201``application/json`
6 fields
Account creation successful.
| Field | Type | Description |
| --- | --- | --- |
| `account_id`required | `string` | Account IDExample `f2ee7908-daee-4da0-9cbe-f8dbcb9dab53` |
| `account_key`required | `string` | Account KeyExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
| `organization_id`required | `string` | Organization IDExample `fxfxfxfx-fxfxfxfx-fxfxfxfx-fxfxfxfx` |
| `first_name`required | `string` | Customer first nameExample `Alan` |
| `last_name`required | `string` | Customer last nameExample `Turing` |
| `email`required | `string` | Customer email addressExample `Alan.Turing@example.com` |
##### Other responses
`400`
`POST` `/confirm-email`
#### Confirm Customer Email
`post-confirm-email`
This service confirms the customer email and return the user key.
A confirmation token must be provided. This confirmation token can be found on the query parameters of the confirmation button URL address on the email sent by Customer Creation service.
Once the customer email is confirmed, the service will continue to provide the user key in the response for 1 hour. After 1 hour, the user key will not be provided in the response anymore.
##### Request
application/json Copy Example of a successful email confirmation.
```
{
"confirmation_token": ""
}
```
##### Response
application/json Copy Email confirmed successful.
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `confirmation_token` | `string` | A confirmation token. This confirmation token can be found on the query parameters of the confirmation button URL address on the email sent by Customer Creation service.Example `` |
##### Response `200``application/json`
1 fields
Email was already confirmed previously.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Email was already confirmed previously. |
##### Response `201``application/json`
1 fields
Email confirmed successful.
| Field | Type | Description |
| --- | --- | --- |
| `api_key` | `string` | User API key. |
##### Other responses
`400`
`GET` `/retrieve-account`
#### Retrieve Account
`retrieve_account`
This service is used to retrieve account details by API_key
When a customer account is created, the API_key is send to the customer by email. This can be used on this service to retrieve the customer account details
##### Response
200400500
application/json Copy 200 response
```
{
"account_id": "1f4bf452-1da2-8f6c-976c-8a779523156a",
"company_name": "FoobarINC",
"email": "example@email.com",
"first_name": "John",
"last_name": "Doe"
}
```
application/json Copy 400 response
```
{
"message": "The query string parameter must contain the api_key parameter. Please use /retrieve-account?api_key="
}
```
application/json Copy 500 response
```
{
"message": "Internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `api_key` required | `string` query | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | The api_key that was send to the customer upon account creation. |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `account_id` | `string` | Account unique identifier. |
| `company_name` | `string` | Customer account company name. |
| `email` | `string` | Customer account email. |
| `first_name` | `string` | Customer account first_name. |
| `last_name` | `string` | Customer account last_name. |
##### Response `400``application/json`
1 fields
400 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request. |
##### Response `500``application/json`
1 fields
500 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
### Site Logs
`GET` `/marketing-logs`
#### Get Site Logs
`getMarketingLogs`
Get Marketing Logs
##### Response
200400404
application/json Copy Successfully get Marketing Logs.
```
{
"foo": "bar"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `site_configuration_id` required | `string` query | `some-configuration-id` | Site Configuration ID |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`200`
### Policy Store
`POST` `/policy-store`
#### Create Policy Store
`createPolicyStore`
Creates a policy store. A policy store is a container for policies.
##### Request
application/json Copy
```
{
"description": "Example policy store"
}
```
##### Response
201400404
application/json Copy Successfully created policy store.
```
{
"policy_store_id": "Dc3v9eLa2UbfCrw6wrkcmK"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `description`required | `string` | Description of the policy store.Example `Example policy store` |
##### Response `201``application/json`
1 fields
Successfully created policy store.
| Field | Type | Description |
| --- | --- | --- |
| `policy_store_id`required | `string` | ID of the policy store. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/policy-store`
#### List Policy Stores
`listPolicyStore`
List Policy Store
List created policy stores. A policy store is a container for policies.
##### Response
200400404
application/json Copy Successfully get list of policy stores.
```
{
"next_token": "AQICAHisuNZI1E/P3KXm5hmEqogC7wTB89VLTeJv4gbr",
"policy_stores": [
{
"policy_store_id": "Dc3v9eLa2UbfCrw6wrkcmK",
"description": "test",
"created_at": "2024-04-23T20:35:36.300514+00:00",
"updated_at": "2024-04-23T20:35:36.300514+00:00"
}
]
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `limit` | `integer` query | `5` | Number of policy stores to return. |
| `next_token` | `string` query | `null` | Next token. |
##### Response `200``application/json`
2 fields
Successfully get list of policy stores.
| Field | Type | Description |
| --- | --- | --- |
| `policy_stores`required | `object[]` | Policy stores array. |
| `policy_store_id`required | `string` | ID of the policy store. |
| `description`required | `string` | Description of the policy store. |
| `created_at`required | `string (date-time)` | Creation date of the policy store. |
| `updated_at`required | `string (date-time)` | Last update date of the policy store. |
| `next_token`required | `string` | Next token. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`DELETE` `/policy-store/{policy_store_id}`
#### Delete Policy Store
`deletePolicyStore`
Delete policy store. A policy store is a container for policies.
##### Response
400404
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`204`
`PUT` `/policy-store/{policy_store_id}`
#### Update Policy Store
`updatePolicyStore`
Update policy store. A policy store is a container for policies.
##### Response
200400404
application/json Copy Successfully updated policy store.
```
{
"message": "Policy store updated successfully."
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
##### Response `200``application/json`
1 fields
Successfully updated policy store.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Message |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Policy
`POST` `/policy-store/{policy_store_id}/policy`
#### Create Policy
`createPolicy`
Creates a Cedar policy and saves it in the specified policy store.
A policy is a statement that either permits or forbids a principal to take one or more actions on a resource. Each policy is evaluated independently of any other policy. For more information about how Cedar policies are structured and evaluated, see
Example of Cedar policy that permits a borrower to get property information on a specific property:
Show the rest
```
permit(principal == ExampleCo::Loan::Borrower::\"John\",action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"],resource == ExampleCo::Loan::Property::\"154 Road\") when {true};
```
Example of Cedar policy that permits a borrower to get property information on any property:
```
permit(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource) when {true};
```
Example of Cedar policy that forbids a borrower to get property information on a specific property:
```
forbid(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource == ExampleCo::Loan::Property::\"154 Road\") when {true};
```
##### Request
Permits a borrower to get property information on a specific propertyPermits a borrower to get property information on any propertyForbids a borrower to get property information on a specific property
application/json Copy
```
{
"definition": "permit(principal == ExampleCo::Loan::Borrower::\"John\",action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"],resource == ExampleCo::Loan::Property::\"154 Road\") when {true};",
"description": "example"
}
```
application/json Copy
```
{
"definition": "permit(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource) when {true};",
"description": "example"
}
```
application/json Copy
```
{
"definition": "forbid(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource == ExampleCo::Loan::Property::\"154 Road\") when {true};",
"description": "example"
}
```
##### Response
201400404
application/json Copy Successfully created policy.
```
{
"policy_id": "CR3KDTmvdYUGoPFeUapsFY"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `definition`required | `string` | Cedar policy definition.Example `permit(principal,action,resource) when {principal.owner == resource.owner};"}}` |
| `description` | `string` | Description of the policy.Example `example` |
##### Response `201``application/json`
1 fields
Successfully created policy.
| Field | Type | Description |
| --- | --- | --- |
| `policy_id`required | `string` | ID of the policy. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/policy-store/{policy_store_id}/policy`
#### List Policies
`listPolicies`
List created policies.
##### Response
200400404
application/json Copy Successfully get list of policies.
```
{
"next_token": null,
"policies": [
{
"policy_id": "QYihkmqrnZTSvzQNhbpcjR",
"description": "example",
"principal": {
"entityType": "loan::borrower",
"entityId": "john"
},
"resource": {
"entityType": "loan::preapprovallist",
"entityId": "johnlist"
},
"created_at": "2024-04-22T16:50:10.977564+00:00",
"updated_at": "2024-04-22T16:50:10.977564+00:00"
}
]
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
| `limit` | `integer` query | `5` | Number of policies to return. |
| `next_token` | `string` query | `null` | Next token. |
##### Response `200``application/json`
2 fields
Successfully get list of policies.
| Field | Type | Description |
| --- | --- | --- |
| `policies`required | `object[]` | Policies array. |
| `policy_id`required | `string` | ID of the policy. |
| `description`required | `string` | Description of the policy. |
| `principal`required | `object` | Principal of the policy. |
| `resource`required | `object` | Resource of the policy. |
| `created_at`required | `string (date-time)` | Creation date of the policy. |
| `updated_at`required | `string (date-time)` | Last update date of the policy. |
| `next_token`required | `string` | Next token. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`DELETE` `/policy-store/{policy_store_id}/policy/{policy_id}`
#### Delete Policy
`deletePolicy`
Delete policy.
##### Response
400404
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
| `policy_id` required | `string` path | `CR3KDTmvdYUGoPFeUapsFY` | ID of the policy. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`204`
`PUT` `/policy-store/{policy_store_id}/policy/{policy_id}`
#### Update Policy
`updatePolicy`
Update policy.
##### Request
Permits a borrower to get property information on a specific propertyPermits a borrower to get property information on any propertyForbids a borrower to get property information on a specific property
application/json Copy
```
{
"definition": "permit(principal == ExampleCo::Loan::Borrower::\"John\",action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"],resource == ExampleCo::Loan::Property::\"154 Road\") when {true};",
"description": "example"
}
```
application/json Copy
```
{
"definition": "permit(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource) when {true};",
"description": "example"
}
```
application/json Copy
```
{
"definition": "forbid(principal == ExampleCo::Loan::Borrower::\"John\", action in [ExampleCo::Loan::Action::\"GetPropertyInfo\"], resource == ExampleCo::Loan::Property::\"154 Road\") when {true};",
"description": "example"
}
```
##### Response
200400404
application/json Copy Successfully updated policy store.
```
{
"message": "Policy store updated successfully."
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
| `policy_id` required | `string` path | `CR3KDTmvdYUGoPFeUapsFY` | ID of the policy. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `definition`required | `string` | Cedar policy definition.Example `permit(principal,action,resource) when {principal.owner == resource.owner};"}}` |
| `description` | `string` | Description of the policy.Example `example` |
##### Response `200``application/json`
1 fields
Successfully updated policy store.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Message |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/policy-store/{policy_store_id}/policy/{policy_id}`
#### Get Policy
`getPolicy`
Delete Policy
Get policy.
##### Response
200400404
application/json Copy Successfully deleted policy.
```
{
"principal": {
"entityType": "loan::borrower",
"entityId": "john"
},
"resource": {
"entityType": "loan::preapprovallist",
"entityId": "johnlist"
},
"definition": "permit(\n principal == loan::borrower::\"john\",\n action in [loan::Action::\"ReadPreapprovallist\",loan::Action::\"UpdatePreapprovallist\",loan::Action::\"DeletePreapprovallist\"],\n resource == loan::preapprovallist::\"johnlist\"\n) when {\n true\n};",
"description": "example",
"created_at": "2024-04-22T16:50:10.977564+00:00",
"updated_at": "2024-04-22T16:50:10.977564+00:00"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
| `policy_id` required | `string` path | `CR3KDTmvdYUGoPFeUapsFY` | ID of the policy. |
##### Response `200``application/json`
6 fields
Successfully deleted policy.
| Field | Type | Description |
| --- | --- | --- |
| `principal`required | `object` | Principal of the policy. |
| `resource`required | `object` | Resource of the policy. |
| `definition`required | `string` | Definition of the policy. |
| `description`required | `string` | Description of the policy. |
| `created_at`required | `string (date-time)` | Creation date of the policy. |
| `updated_at`required | `string (date-time)` | Last update date of the policy. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Policy Store Schema
`PUT` `/policy-store/{policy_store_id}/schema`
#### Put Policy Store Schema
`putPolicyStoreSchema`
Creates or updates the policy Cedar json schema in the specified policy store. The schema is used to validate any policies submitted to the policy store. Existing policies and templates are not re-evaluated against the changed schema.
For more information and examples about Cedar schema format, see .
Example of Cedar schema:
```
{
"ExampleCo::Mortgage": {
"actions": {
"GetPropertyInfo": {
"appliesTo": {
"principalTypes": [
"Borrower"
],
"resourceTypes": [
"Property"
]
}
},
"GetListingInfo": {
"appliesTo": {
"principalTypes": [
"Borrower"
],
"resourceTypes": [
"Listing"
]
}
}
},
&Show the restquot;entityTypes": {
"Property": {
"shape": {
"type": "Record",
"attributes": {
"address": {
"type": "String"
},
"property_identifier": {
"type": "String"
},
"loan_identifier": {
"type": "String"
}
}
}
},
"Listing": {
"shape": {
"type": "Record",
"attributes": {
"total_price": {
"type": "String"
},
"listing_identifier": {
"type": "String"
}
}
}
},
"Borrower": {
"shape": {
"attributes": {
"first_name": {
"type": "String"
},
"last_name": {
"type": "String"
},
"person_identifier": {
"type": "String"
},
"loan_identifier": {
"type": "String"
}
},
"type": "Record"
}
}
}
}
}
```
##### Request
application/json Copy
```
{
"definition": {
"ExampleCo::Loan": {
"actions": {
"GetPropertyInfo": {
"appliesTo": {
"principalTypes": [
"Borrower"
],
"resourceTypes": [
"Property"
]
}
}
},
"entityTypes": {
"Property": {
"shape": {
"type": "Record",
"attributes": {}
}
},
"Borrower": {
"shape": {
"attributes": {},
"type": "Record"
}
}
}
}
}
}
```
##### Response
200400404
application/json Copy Successfully created/updated policy store schema.
```
{
"message": "Policy store updated successfully."
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `definition` | `object` | Cedar schema of the policy store. |
##### Response `200``application/json`
1 fields
Successfully created/updated policy store schema.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Message |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/policy-store/{policy_store_id}/schema`
#### Get Policy Store Schema
`getPolicyStoreSchema`
Retrieve defined schema in the specified policy store.
##### Response
200400404
application/json Copy Successfully created/updated policy store schema.
```
{
"schema": {
"ExampleCo::Loan": {
"entityTypes": {
"Borrower": {
"shape": {
"attributes": {},
"type": "Record"
}
},
"Property": {
"shape": {
"attributes": {},
"type": "Record"
}
}
},
"actions": {
"GetPropertyInfo": {
"appliesTo": {
"principalTypes": [
"Borrower"
],
"resourceTypes": [
"Property"
]
}
}
}
}
},
"namespaces": [
"ExampleCo::Loan"
],
"created_at": "2024-04-23T20:33:36.040403+00:00",
"updated_at": "2024-04-24T11:19:28.118220+00:00"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Resource not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `policy_store_id` required | `string` path | `Dc3v9eLa2UbfCrw6wrkcmK` | ID of the policy store. |
##### Response `200``application/json`
4 fields
Successfully created/updated policy store schema.
| Field | Type | Description |
| --- | --- | --- |
| `schema`required | `object` | Policy store schema. |
| `namespaces`required | `string[]` | Namespaces. |
| `created_at`required | `string (date-time)` | Creation date of the policy store schema. |
| `updated_at`required | `string (date-time)` | Last update date of the policy store schema. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Account Data
`POST` `/setup-master-data`
#### Set up Master data
`account_store_new_environment_access`
Set up master Account data
Register the environment and API key, this configuration will set up the Account to retrieve data from the environment, allowing to set up the customer to start working with Staircase products.
The Account data bundle automatically registers the Marketplace environment which includes all needed configurations and credentials to start using Staircase products in the customer environment.
##### Request
application/json Copy .
```
{
"environment": "test2.staircaseapi.com\"",
"api-key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `environment`required | `string` | The environment hostExample `test.staircaseapi.comm` |
| `api-key`required | `string (api-key)` | The API key used in order to access APIs in the hostExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `201``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The message. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL service address. |
| `message` | `string` | The error details. |
`DELETE` `/setup-master-data`
#### Remove Master data
`account_remove_environments_access`
Remove Master Account Data
Removes the environment configuration and data so that it can stop retrieving credentials and configurations from another environment.
##### Response
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `Content-Type` required | `string` header | `application/json` | Content Type |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The message. |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL service address. |
| `message` | `string` | The error details. |
##### Response `404``application/json`
1 fields
404 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The error details. |
### Access Amazon SSO
`POST` `/sso/amazon`
#### Create SSO Configuration
`createSSOConfigurationAmazon`
Create SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "amzn1.application-oa2-client.1234567890abcdef1234567890abcdef",
"client_secret": ""
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Amazon set successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `amzn1.application-oa2-client.1234567890abcdef1234567890abcdef` |
##### Response `201``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Amazon set successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration existent
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`PUT` `/sso/amazon`
#### Update SSO Configuration
`updateSSOConfigurationAmazon`
Update SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "amzn1.application-oa2-client.1234567890abcdef1234567890abcdef",
"client_secret": ""
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Google updated successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `amzn1.application-oa2-client.1234567890abcdef1234567890abcdef` |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Google updated successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/sso/amazon`
#### Get SSO Configuration
`getSSOConfigurationAmazon`
Retrieve SSO configuration set on environment.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"approved_js_origin": "https://auth.env.staircaseapi.com",
"oauth_authorized_redirect": "https://auth.env.staircaseapi.com/oauth2/idpresponse"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `200``application/json`
2 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `approved_js_origin` | `string` | approved_js_origin.Example `https://auth.env.staircaseapi.com` |
| `oauth_authorized_redirect` | `string` | oauth_authorized_redirect.Example `https://auth.env.staircaseapi.com/oauth2/idpresponse` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`DELETE` `/sso/amazon`
#### Delete SSO Configuration
`deleteSSOConfigurationsAmazon`
Delete SSO configuration set on environment.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`204``401``404`
### Access Apple SSO
`POST` `/sso/apple`
#### Create SSO Configuration
`createSSOConfigurationApple`
Create SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "com.example.app",
"team_id": "ABCDEFGH12345678",
"key_id": "XYZ1234567890",
"private_key": ""
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Apple set successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `client_id` |
| `team_id`required | `string (team_id)` | SSO provider team id.Example `team_id` |
| `key_id`required | `string (key_id)` | SSO provider key id.Example `team_id` |
| `private_key`required | `string (private_key)` | SSO provider private key.Example `` |
##### Response `201``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Apple set successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration existent
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`PUT` `/sso/apple`
#### Update SSO Configuration
`updateSSOConfigurationApple`
Update SSO configuration on environment. Providers Supported: Google.
##### Request
application/json Copy
```
{
"client_id": "com.example.app",
"team_id": "ABCDEFGH12345678",
"key_id": "XYZ1234567890",
"private_key": ""
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Apple updated successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `client_id` |
| `team_id`required | `string (team_id)` | SSO provider team id.Example `team_id` |
| `key_id`required | `string (key_id)` | SSO provider key id.Example `team_id` |
| `private_key`required | `string (private_key)` | SSO provider private key.Example `` |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Apple updated successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/sso/apple`
#### Get SSO Configuration
`getSSOConfigurationApple`
Retrieve SSO configuration set on environment.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"approved_js_origin": "https://auth.env.staircaseapi.com",
"oauth_authorized_redirect": "https://auth.env.staircaseapi.com/oauth2/idpresponse"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `200``application/json`
2 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `approved_js_origin` | `string` | approved_js_origin.Example `https://auth.env.staircaseapi.com` |
| `oauth_authorized_redirect` | `string` | oauth_authorized_redirect.Example `https://auth.env.staircaseapi.com/oauth2/idpresponse` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`DELETE` `/sso/apple`
#### Delete SSO Configuration
`deleteSSOConfigurationsApple`
Delete SSO configuration set on environment.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`204``401``404`
### Access Facebook SSO
`POST` `/sso/facebook`
#### Create SSO Configuration
`createSSOConfigurationFacebook`
Create SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "1234567890123456",
"client_secret": ""
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Facebook set successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `client_id` |
##### Response `201``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Facebook set successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration existent
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`PUT` `/sso/facebook`
#### Update SSO Configuration
`updateSSOConfigurationFacebook`
Update SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "1234567890123456",
"client_secret": ""
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Facebook updated successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `client_id` |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Facebook updated successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/sso/facebook`
#### Get SSO Configuration
`getSSOConfigurationFacebook`
Retrieve SSO configuration set on environment.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"approved_js_origin": "https://auth.env.staircaseapi.com",
"oauth_authorized_redirect": "https://auth.env.staircaseapi.com/oauth2/idpresponse"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `200``application/json`
2 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `approved_js_origin` | `string` | approved_js_origin.Example `https://auth.env.staircaseapi.com` |
| `oauth_authorized_redirect` | `string` | oauth_authorized_redirect.Example `https://auth.env.staircaseapi.com/oauth2/idpresponse` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`DELETE` `/sso/facebook`
#### Delete SSO Configuration
`deleteSSOConfigurationsFacebook`
Delete SSO configuration set on environment.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`204``401``404`
### Access Google SSO
`POST` `/sso/google`
#### Create SSO Configuration
`createSSOConfiguration`
Create SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "20581095937-l92gfggdj4tl5gn227g90.apps.googleusercontent.com",
"client_secret": ""
}
```
##### Response
201400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Google set successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `GOCSPX-MUIzom5cbFWaJs4AOIJE8JNr` |
##### Response `201``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Google set successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration existent
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`PUT` `/sso/google`
#### Update SSO Configuration
`updateSSOConfiguration`
Update SSO configuration on environment.
##### Request
application/json Copy
```
{
"client_id": "20581095937-l92gfggdj4tl5gn227g90.apps.googleusercontent.com",
"client_secret": ""
}
```
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"message": "SSO configuration Google updated successfully"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `client_secret`required | `string (client_secret)` | SSO provider client secret.Example `` |
| `client_id`required | `string (client_id)` | SSO provider client id.Example `GOCSPX-MUIzom5cbFWaJs4AOIJE8JNr` |
##### Response `200``application/json`
1 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration message.Example `SSO configuration Google updated successfully` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
SSO Configuration Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/sso/google`
#### Get SSO Configuration
`getSSOConfiguration`
Retrieve SSO configuration set on environment.
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"approved_js_origin": "https://auth.env.staircaseapi.com",
"oauth_authorized_redirect": "https://auth.env.staircaseapi.com/oauth2/idpresponse"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `200``application/json`
2 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `approved_js_origin` | `string` | approved_js_origin.Example `https://auth.env.staircaseapi.com` |
| `oauth_authorized_redirect` | `string` | oauth_authorized_redirect.Example `https://auth.env.staircaseapi.com/oauth2/idpresponse` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
`DELETE` `/sso/google`
#### Delete SSO Configuration
`deleteSSOConfigurations`
Delete SSO configuration set on environment.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `409``application/json`
1 fields
User not confirmed
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`204``401``404`
### Access SSO
`GET` `/{application_name}/sso/{sso_provider}`
#### Get SSO by Application
`getSSOApp`
Get SSO Links retrieves the sing-up/sing-in and logout links needed for managing SSO logged users. Providers Supported: `Google`,`Facebook`,`SignInWithApple`,`LoginWithAmazon`
There are two types of grants:
- Authorization Code Grant
- Implicit Grant
The Authorization Code Grant will return `access_token` and `id_token` as a URL fragments in the `redirect_uri` The Implicit Grant will return `access_token` and `id_token` AND `refresh_token` as a URL fragments in the `redirect_uri`
##### Response
200400 application/json400 text/html
application/json Copy OK response
```
[
{
"sso_provider": "Google",
"sso_signin_link": "https://auth.cerf-dev.staircaseapi.com/oauth2/authorize?identity_provider=Google&redirect_uri=https://webhook.site/123&response_type=token&client_id=6066huk2cnnuln4f2ajg71jnmv&scope=email+openid+profile",
"sso_logout_link": "https://auth.cerf-dev.staircaseapi.com/logout?logout_uri=https://webhook.site/123&response_type=token&client_id=6066huk2cnnuln4f2ajg71jnmv"
}
]
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sso_provider` required | `string` path | `Google` | SSO provider. |
| `application_name` required | `string` path | `access` | Application name. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY |
##### Response `200``application/json`
3 fields
OK response
| Field | Type | Description |
| --- | --- | --- |
| `sso_provider` | `string` | Configuration message.Example `Google, SSO configurations set` |
| `sso_signin_link` | `string` | Redirect UI added.Example `https://ui.redirect/logged/users` |
| `sso_logout_link` | `string` | Redirect UI added.Example `https://ui.redirect/logged/users` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `429``application/json`
1 fields
To many requests
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401``404`
### Operations
`GET` `/smoke`
#### Smoke endpoint
Endpoint to check service health
##### Other responses
`200`
`POST` `/tenants`
#### Create necessary AWS instances for new tenant
Tenant is client of staircase. When a new client registers we should create virtual infrastructure for him: create new domain in format {tenant_name}.api.stairacaseapi.com, map specified API to {tenant_name}.api.stairacaseapi.com/{base_path}, create new usage plan with {tenant_name} name for API's specified in api_mapping. That what this endpoint does.
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `tenant_name` | `string` | — |
| `api_mapping` | `array` | — |
##### Response `202``application/json`
2 fields
202 response
| Field | Type | Description |
| --- | --- | --- |
| `start_time` | `string` | — |
| `status` | `string` | — |
##### Other responses
`400`
`POST` `/tenants/{tenant_name}/keys`
#### Generate API key
Generate API key for specified tenant and add it to tenant usage plan
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `tenant_name` required | `string` path | Tenant name |
##### Response `201``application/json`
1 fields
201 response
| Field | Type | Description |
| --- | --- | --- |
| `x-api-key` | `string` | — |
## Errors
`400``401``403``404``409``422``429``500`
## More in Distribution
- Next product: Console
---
# Console
# Console
The configurable application shell every front end was assembled in.
An application in the Console is a configuration rather than a codebase: components, their properties and their ordering, resolved against a shared component library and packaged into a deployable front end.
The library covers the primitives plus custom components built for this domain. Configuration-driven assembly is what carried several interfaces without several front-end codebases.
## How it works
Three systems meet at one identifier. A design file is imported into the cloud provider's own component library, which generates typed components from it; a content system holds the configuration saying which of those components appear, in what order, with what labels, and against which endpoint; and the catalogue holds the record that names the application. All three are keyed on the configuration identifier Marketplace issues, which is what stops the design, the content and the deployment drifting apart.
A list view — the most common shape — is a content record naming a table layout and an endpoint configuration. Building one means duplicating an existing record and editing the labels and the endpoint it reads, so a new screen over an existing API is content work rather than engineering work.
Every interface came out of this shell. A rate calculator, a property-data exchange and a conversational front end are three configurations against one component library, not three codebases.
## Operations
### Console Dashboard UI
`POST` `/auth/password`
#### Change pass
`change-pass`
##### Request
application/json Copy An example of a payload.
```
{
"email": "john.doe@company.com",
"password": "XXXXX"
}
```
##### Response
application/json Copy OK.
```
{
"message": "success"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/auth/sign-in`
#### Sign In
`sign-in`
Sign in
Sign In
##### Request
application/json Copy An example of a payload.
```
{
"email": "john.doe@company.com",
"password": "XXXXX"
}
```
##### Response
application/json Copy OK.
```
{
"message": "success"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/auth/sign-up`
#### Sign Up
`sign-up`
Sign up
Sign Up
##### Request
application/json Copy An example of a payload.
```
{
"email": "john.doe@company.com",
"password": "XXXXX"
}
```
##### Response
application/json Copy OK.
```
{
"message": "success"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Users
`GET` `/author`
#### Get Author
`get_author`
Request author access to a pipeline to be able to:
- Review and modify Dataset
- Create Analysis
- Share Dashboards
To log in to QuickSight:
- Go to
- Use the QuickSight Account Name `account_name`.
- Use the QuickSight User `user_name`.
- Use the QuickSight User Password that was defined while obtaining Author Access.
Please note the Author user is one for all the Staircase environment. It is important to understand that Author will see datasets and analysis from all the pipelines. It is recommended to use `Shared folders` in Quicksight to see datasets organized by `pipeline_name`.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
### Console API
`GET` `/configurations`
#### Get configuration
`get_configuration`
Get configurations
##### Response
application/json Copy Ok.
```
{
"collections": [
{
"metadata": {
"serialise_to_graph": true,
"fuzzy_searchable": false,
"validation": true,
"version": 3,
"created_at": "2023-05-26T02:09:23.253331-04:00"
},
"collection_id": "01H1BAT4SNVDE9HYEBZD04MNEH",
"data": {
"companies": [
{
"@id": "01H1BAT4TZW1HXZ0RZPYK52VFV",
"@type": "company",
"company_identifier": "grate-company-id"
},
{
"@id": "01H1BAT4TZ7T9THN4MEZ9E4MMV",
"@type": "company",
"company_identifier": "staircase-company-id"
},
{
"@id": "01H1BAT4TZ6FB1ZABFM8MQGFTH",
"@type": "company",
"company_identifier": "ice-company-id"
},
{
"@id": "01H1BAT4TZ45T2C6K39CMGQQKB",
"@type": "company",
"company_identifier": "ice-company-id"
},
{
"@id": "01H1BAT4TZJ01KM1WEPRZEZHKM",
"@type": "company"
}
],
"consoles": [
{
"@id": "01H1BAT4TYBW7FJQNSB9KXXB28",
"@type": "console",
"console_configuration_type": "listView",
"datocms_class_name": "TeamVelocity",
"datocms_identifier": "123456789",
"has_permission": [
"01H1BAT4TZNZSWRWX738J7KJ96",
"01H1BAT4TZCRVFH26GS24DMCQG",
"01H1BAT4TZAGXKEG5N4Z3STD30",
"01H1BAT4TZ9XSSYVRC35APTJ51",
"01H1BAT4TZ1ECXC6FM40W98VVR"
],
"title": "Team Velocity List View"
}
],
"permissions": [
{
"@id": "01H1BAT4TZNZSWRWX738J7KJ96",
"@type": "permission",
"company_contact_role_type": "CFO",
"has_company": "01H1BAT4TZ6FB1ZABFM8MQGFTH"
},
{
"@id": "01H1BAT4TZAGXKEG5N4Z3STD30",
"@type": "permission",
"company_contact_role_type": "CFO",
"has_company": "01H1BAT4TZJ01KM1WEPRZEZHKM"
},
{
"@id": "01H1BAT4TZCRVFH26GS24DMCQG",
"@type": "permission",
"has_company": "01H1BAT4TZW1HXZ0RZPYK52VFV"
},
{
"@id": "01H1BAT4TZ1ECXC6FM40W98VVR",
"@type": "permission",
"has_company": "01H1BAT4TZ7T9THN4MEZ9E4MMV"
},
{
"@id": "01H1BAT4TZ9XSSYVRC35APTJ51",
"@type": "permission",
"company_contact_role_type": "CEO",
"has_company": "01H1BAT4TZ45T2C6K39CMGQQKB"
}
],
"product_configurations": [
{
"@type": "product_configuration",
"product_configuration_identifier": "marketpace-ontology-configuration-id-of-the-screen",
"@id": "01H1BAT4TZC99WK5CWFMJZ3G9H"
}
]
},
"transaction_id": "01H1BAT4G004ZKK5DXF1GB87YV"
}
],
"next_token": null
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `token` | Next token for listing |
##### Other responses
`200`
`POST` `/configurations`
#### Create configuration
`create_configuration`
##### Request
application/json Copy
```
{
"product_configuration_identifier": "marketpace-ontology-configuration-id-of-the-screen",
"title": "Team Velocity List View",
"datocms_identifier": "123456789",
"datocms_class_name": "TeamVelocity",
"url_suffix": "/team-velocity",
"configuration_type": "listView",
"permissions": [
{
"has_company": "staircase-company-id"
},
{
"has_company": "ice-company-id",
"company_contact_role_type": "CEO"
},
{
"has_company": "ice-company-id",
"company_contact_role_type": "CFO"
},
{
"company_contact_role_type": "CFO"
},
{
"has_company": "grate-company-id"
}
]
}
```
##### Response
200400
application/json Copy Ok.
```
{
"message": "created",
"transaction_id": "01H1KQAXKB77A2PA1QSS1YEDQD",
"collection_id": "01H1KQAXXWA6CR4ZSJPSHCGDGB"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is not valid JSON."
}
```
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
`GET` `/configurations/{configuration_id}`
#### Get configuration
`get_configurations`
##### Response
application/json Copy Ok.
```
{
"collections": [
{
"metadata": {
"serialise_to_graph": true,
"fuzzy_searchable": false,
"validation": true,
"version": 3,
"created_at": "2023-05-26T02:09:23.253331-04:00"
},
"collection_id": "01H1BAT4SNVDE9HYEBZD04MNEH",
"data": {
"companies": [
{
"@id": "01H1BAT4TZW1HXZ0RZPYK52VFV",
"@type": "company",
"company_identifier": "grate-company-id"
},
{
"@id": "01H1BAT4TZ7T9THN4MEZ9E4MMV",
"@type": "company",
"company_identifier": "staircase-company-id"
},
{
"@id": "01H1BAT4TZ6FB1ZABFM8MQGFTH",
"@type": "company",
"company_identifier": "ice-company-id"
},
{
"@id": "01H1BAT4TZ45T2C6K39CMGQQKB",
"@type": "company",
"company_identifier": "ice-company-id"
},
{
"@id": "01H1BAT4TZJ01KM1WEPRZEZHKM",
"@type": "company"
}
],
"consoles": [
{
"@id": "01H1BAT4TYBW7FJQNSB9KXXB28",
"@type": "console",
"console_configuration_type": "listView",
"datocms_class_name": "TeamVelocity",
"datocms_identifier": "123456789",
"has_permission": [
"01H1BAT4TZNZSWRWX738J7KJ96",
"01H1BAT4TZCRVFH26GS24DMCQG",
"01H1BAT4TZAGXKEG5N4Z3STD30",
"01H1BAT4TZ9XSSYVRC35APTJ51",
"01H1BAT4TZ1ECXC6FM40W98VVR"
],
"title": "Team Velocity List View"
}
],
"permissions": [
{
"@id": "01H1BAT4TZNZSWRWX738J7KJ96",
"@type": "permission",
"company_contact_role_type": "CFO",
"has_company": "01H1BAT4TZ6FB1ZABFM8MQGFTH"
},
{
"@id": "01H1BAT4TZAGXKEG5N4Z3STD30",
"@type": "permission",
"company_contact_role_type": "CFO",
"has_company": "01H1BAT4TZJ01KM1WEPRZEZHKM"
},
{
"@id": "01H1BAT4TZCRVFH26GS24DMCQG",
"@type": "permission",
"has_company": "01H1BAT4TZW1HXZ0RZPYK52VFV"
},
{
"@id": "01H1BAT4TZ1ECXC6FM40W98VVR",
"@type": "permission",
"has_company": "01H1BAT4TZ7T9THN4MEZ9E4MMV"
},
{
"@id": "01H1BAT4TZ9XSSYVRC35APTJ51",
"@type": "permission",
"company_contact_role_type": "CEO",
"has_company": "01H1BAT4TZ45T2C6K39CMGQQKB"
}
],
"product_configurations": [
{
"@type": "product_configuration",
"product_configuration_identifier": "marketpace-ontology-configuration-id-of-the-screen",
"@id": "01H1BAT4TZC99WK5CWFMJZ3G9H"
}
]
},
"transaction_id": "01H1BAT4G004ZKK5DXF1GB87YV"
}
],
"next_token": null
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `configuration_id` required | `string` path | `product_configuration_identifier` | querying by $.product_configurations[*].product_configuration_identifier |
##### Other responses
`200`
### Dashboard
`PUT` `/dashboard/dashboards/costs-and-revenue`
#### Update Costs/Revenue Dashboard
`updateCostsRevenueDashboard`
Starts the update of the GTL costs/revenue dashboard with metrics from Health and costs from AWS Cost Explorer.
##### Response `202``application/json`
1 fields
Update is started.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message about update is started. |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Dashboards
`GET` `/dashboards`
#### Get Dashboards
`get_all_dashboards`
Get embedded link for all dashboards. Going to return all the links to all the dashboards.
Response includes:
- `id` - Dashboard ID
- `name` - Dashboard name
- `embedded_url` - Embedded URL. Links are QuickSight native with a temporary authentication token. So they can not be used for permanent share.
- `public_url` - Public URL. This is a permanent link that can be used to share Dashboard outside the Staircase.
It is good idea to use `embedded_link` inside a web page or web application that have authentication.
Important, `public_url` can be used without `API_KEY`. Please do not share it if Dashboard has sensitive data.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Response `200``application/json`
4 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Dashboard ID |
| `name`required | `string` | Dashboard name |
| `embedded_url`required | `string` | Embedded URL |
| `public_url`required | `string` | Public URL |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`GET` `/dashboards/{dashboard_id}/public-url`
#### Get Public Url
`get_gashboard_public_url`
Get Public URL
Get dashboard public URL. It is required to specify:
- `dashboard_id` - Dashboard ID from the Get Dashboards
As it can be invoked without API_KEY only, it can NOT be used to share sensitive data.
For now, this is the only endpoint that can be used for permanent share.
##### Response
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `dashboard_id` required | `string` path | `dashboard_id` | Dashboard ID |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`307``404`
### Datalakes
`PUT` `/datalakes`
#### Create or Update
`create_datalake`
Create or Update Datalake
##### Request
application/json Copy
```
{
"name": "pipe01",
"verbose_name": "Pipeline 01",
"dataset": {
"columns": [
{
"Name": "IMPORT_COMPLETED",
"Type": "int"
},
{
"Name": "ONBOARDING_STARTED",
"Type": "int"
},
{
"Name": "CLASSIFICATION_STARTED",
"Type": "int"
},
{
"Name": "CLASSIFICATION_COMPLETED",
"Type": "int"
},
{
"Name": "EXTRACTION_COMPLETED",
"Type": "int"
},
{
"Name": "ONBOARDING_COMPLETED",
"Type": "int"
},
{
"Name": "EXPORT_COMPLETED",
"Type": "int"
},
{
"Name": "DELIVER_COMPLETED",
"Type": "int"
},
{
"Name": "date",
"Type": "timestamp"
}
]
}
}
```
##### Response
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `verbose_name` | `string` | Pipeline Verbose Name |
| `description` | `string` | Pipeline Description |
| `job` | `object` | Pipeline Job |
| `definition`required | `object` | Job Definition |
| `StartAt`required | `string` | The first state |
| `States`required | `object` | Job States |
| `STATE_NAME` | `object` | Name of the State |
| `trigger_schedule_expression`required | `string` | Pipeline Trigger Schedule Expression |
| `triggers` | `array` | Triggers |
| `dataset` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `datasets` | `object` | Pipeline Datasets |
| `DATASET_NAME` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `product_name` | `string` | Staircase product name |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200`
`GET` `/datalakes`
#### Get All
`get_datalakes`
Get All Datalakes
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` | `string` query | `Product Name` | Product Name |
##### Response `200``application/json`
9 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `status` | `string` | Pipeline status`COMPLETED``FAILED``IN_PROGRESS` |
| `operation` | `string` | Pipeline operation`CREATE``DELETE``REVIEW``ROLLBACK``UPDATE``UPDATE_ROLLBACK` |
| `product_name` | `string` | Product name |
| `verbose_name` | `string` | Pipeline Verbose name |
| `job_name` | `string` | Pipeline Job name |
| `job_trigger_names` | `string[]` | Pipeline Job Trigger name |
| `created_at` | `string` | Pipeline create date |
| `updated_at` | `string` | Pipeline Success update date |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
### Datalake
`GET` `/datalakes/{name}`
#### Get One
`get_datalake`
Get pipeline
Retrieve datalake information, such as:
- `status`
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
9 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `status` | `string` | Pipeline status`COMPLETED``FAILED``IN_PROGRESS` |
| `operation` | `string` | Pipeline operation`CREATE``DELETE``REVIEW``ROLLBACK``UPDATE``UPDATE_ROLLBACK` |
| `product_name` | `string` | Product name |
| `verbose_name` | `string` | Pipeline Verbose name |
| `job_name` | `string` | Pipeline Job name |
| `job_trigger_names` | `string[]` | Pipeline Job Trigger name |
| `created_at` | `string` | Pipeline create date |
| `updated_at` | `string` | Pipeline Success update date |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`DELETE` `/datalakes/{name}`
#### Delete One
`delete_datalake`
Delete datalake
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`GET` `/datalakes/{name}/config`
#### Get Config
`get_datalake_config`
Retrieve Datalake configuration.
##### Response
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
7 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `verbose_name` | `string` | Pipeline Verbose Name |
| `description` | `string` | Pipeline Description |
| `job` | `object` | Pipeline Job |
| `definition`required | `object` | Job Definition |
| `StartAt`required | `string` | The first state |
| `States`required | `object` | Job States |
| `STATE_NAME` | `object` | Name of the State |
| `trigger_schedule_expression`required | `string` | Pipeline Trigger Schedule Expression |
| `triggers` | `array` | Triggers |
| `dataset` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `datasets` | `object` | Pipeline Datasets |
| `DATASET_NAME` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `product_name` | `string` | Staircase product name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`404`
### Pipelines
`PUT` `/pipelines`
#### Create or Update
`create_pipeline`
Create or Update Pipeline will enable creation of a new pipeline or update of existing one. To create a new pipeline, you need to provide the below information:
- `name`
- `description` (Optional)
- `product_name` (Optional)
- `job` (Optional)
- `dataset` (Deprecated)
- `datasets`
One of `dataset` or `datasets` is Required.
Show the rest
#### Job
`job` consist of:
- `definition` Definition of a job as it is described in Job documentation. Job Definition
- `trigger_schedule_expression` (Deprecated) Trigger schedule expression. Create Trigger
- `triggers` Triggers definition, that contains `trigger_schedule_expression` and `request_payload`.
`trigger_schedule_expression` and `triggers` are optional. Only one of `trigger_schedule_expression` or `triggers` can be used.
If `job` not specified, it is required to use Put Data operation
##### `definition`
Job definition as it is described in the Create Job
There are few recommendations to consider:
###### Save Data
As of now, Job definition should contain a step that saves data to a pipeline
Save data example
```
{
"SaveData": {
"End": true,
"Method": "POST",
"Path": "console-pipeline/pipelines/{pipeline_name}/data",
"PathParameters": {
"pipeline_name": "$.outputs.Start.pipeline_name"
},
"RequestPayload": "$.outputs.Health.response_payload.metrics",
"Type": "InvokeProduct"
}
}
```
###### Get Latest from a pipeline
it is also recommended to start job definition from getting latest data from a pipeline Get Latest data example
```
{
"LatestData": {
"ExceptNext": "Health",
"Method": "GET",
"Next": "Health",
"Path": "console-pipeline/pipelines/{pipeline_name}/data/latest?sort_column=created_at",
"PathParameters": {
"pipeline_name": "$.outputs.Start.pipeline_name"
},
"Projection": {
"created_at": "$jmespath.created_at | date_format(@, '%Y-%m-%d %H:%M:%S.%f', '%Y-%m-%d')"
},
"Type": "InvokeProduct"
}
}
```
###### Use `pipeline_name` from request_payload
Dashboard Pipeline will Execute Job with `request_payload`, where `pipeline_name` equals Dashboard Pipeline `name`.
To be able to run
```
PathParameters:
pipeline_name: $.request_payload.pipeline_name
```
##### `trigger_schedule_expression`
A rate expression starts when you create the pipeline, and then runs on its defined schedule. Rate expressions have two required fields. Fields are separated by white space.
Syntax `rate(value unit)`
Where:
- `value` a positive number
- `unit` the unit of time.
Different units are required for values of 1, such as minute, and values over 1, such as minutes. Valid values: `minute` | `minutes` | `hour` | `hours` | `day` | `days`
Example of `trigger_schedule_expression` definition
```
{
"trigger_schedule_expression": "rate(1 day)"
}
```
##### `triggers`
Allow to specify one or more executions for the pipeline. Can be used to run pipeline many times with different `request_payload`.
Consist of:
- `trigger_schedule_expression`. For more information please see `trigger_schedule_expression` documentation
- `request_payload` (Optional)
`triggers` can be used to collection data from different Staircase accounts by specifying host and api_key in the `request_payload`.
Maximum number of `triggers` is 100.
Example of `triggers` definition
```
{
"triggers": [
{
"trigger_schedule_expression": "rate(1 day)",
"request_payload": {
"Host": "documentation.staicaseapi.com",
"ApiKey": "API_KEY"
}
}
]
}
```
Another example a `trigger` with custom payload, containing some data and some Staircase environment informations.
```
{
"triggers": [
{
"trigger_schedule_expression": "rate(1 day)",
"request_payload": {
"my_custom_data": {
"foo": "bar"
},
"Env_A": {
"my_host": "A.staicaseapi.com",
"my_api_key": "API_KEY"
},
"Env_B": {
"my_host": "B.staicaseapi.com",
"my_api_key": "API_KEY"
}
}
}
]
}
```
#### Datasets
Allow to define more than one dataset in a Pipeline. Datasets definition contains Dataset Name and Dataset Configuration in a form of JSON object `key` and `value`
Example of a Pipeline that have 2 datasets
```
{
"datasets": {
"sales": {
"columns": [
{
"Name": "start_date",
"Type": "timestamp"
},
{
"Name": "transaction_id",
"Type": "string"
}
]
},
"communications": {
"columns": [
{
"Name": "sent_date",
"Type": "timestamp"
},
{
"Name": "transaction_id",
"Type": "string"
}
]
}
}
}
```
#### Dataset
`dataset` consist of:
- `columns`
- `calculated_columns` (Optional)
##### `columns`
Is an array of column definitions. Columns from this array will be available in the QuickSight dataset. At least one column is required in `columns` array.
Column definition consist of:
- `Name`
- `Type` one of the following types: `int`, `float`, `string`, `timestamp` The following example creates pipeline with `job` and `dataset`. It will run pipeline every 5 mins. Will generate some random data for "metric_number", "metric_status" and "date".
```
{
"name": "pipe1",
"verbose_name": "Pipe 1",
"job": {
"definition": {
"StartAt": "StartFrom",
"States": {
"StartFrom": {
"Type": "InvokeProduct",
"Method": "POST",
"Path": "console-pipeline/generate_data_example",
"Next":"SaveRandomData"
},
"SaveRandomData": {
"Type": "InvokeProduct",
"Method": "POST",
"Path": "console-pipeline/pipelines/{pipeline_name}/data",
"PathParameters": {
"pipeline_name": "pipe1"
},
"RequestPayload": "$.outputs.StartFrom.response_payload",
"End": true
}
}
},
"trigger_schedule_expression": "rate(5 minutes)"
},
"dataset": {
"columns": [
{
"Name": "metric_number",
"Type": "int"
},
{
"Name": "metric_status",
"Type": "string"
},
{
"Name": "date",
"Type": "timestamp"
}
]
}
}
```
##### `calculated_columns`
It is an array of QuickSight Calculated Columns.
Calculated column definition consists of:
- `Name`
- `Expression` - Calculated Columns expression to calculate a value
`Expression` transform `columns` by using one or more of the following:
- Operators
- Functions
- Aggregate functions (you can only add these to an analysis)
- Fields that contain data
- Other calculated fields
```
{
"calculated_columns": [
{
"Name":"status_len",
"Expression": "strlen({status})"
},
{
"Name":"now",
"Expression": "now"
}
]
}
```
##### Request
ExamplePipelineDatasetOnlyHealthIntegration
application/json Copy
```
{
"name": "pipe1",
"verbose_name": "Pipe 1",
"job": {
"definition": {
"StartAt": "StartFrom",
"States": {
"StartFrom": {
"Type": "InvokeProduct",
"Method": "POST",
"Path": "console-pipeline/generate_data_example",
"Next": "SaveRandomData"
},
"SaveRandomData": {
"Type": "InvokeProduct",
"Method": "POST",
"Path": "console-pipeline/pipelines/{pipeline_name}/data",
"PathParameters": {
"pipeline_name": "pipe1"
},
"RequestPayload": "$.outputs.StartFrom.response_payload",
"End": true
}
}
},
"trigger_schedule_expression": "rate(5 minutes)"
},
"dataset": {
"columns": [
{
"Name": "metric_number",
"Type": "int"
},
{
"Name": "metric_status",
"Type": "string"
},
{
"Name": "date",
"Type": "timestamp"
}
]
}
}
```
application/json Copy
```
{
"name": "pipe01",
"verbose_name": "Pipeline 01",
"dataset": {
"columns": [
{
"Name": "IMPORT_COMPLETED",
"Type": "int"
},
{
"Name": "ONBOARDING_STARTED",
"Type": "int"
},
{
"Name": "CLASSIFICATION_STARTED",
"Type": "int"
},
{
"Name": "CLASSIFICATION_COMPLETED",
"Type": "int"
},
{
"Name": "EXTRACTION_COMPLETED",
"Type": "int"
},
{
"Name": "ONBOARDING_COMPLETED",
"Type": "int"
},
{
"Name": "EXPORT_COMPLETED",
"Type": "int"
},
{
"Name": "DELIVER_COMPLETED",
"Type": "int"
},
{
"Name": "date",
"Type": "timestamp"
}
]
}
}
```
application/json Copy
```
{
"name": "myhealth01",
"verbose_name": "My Health 01",
"job": {
"definition": {
"StartAt": "Start",
"States": {
"Start": {
"Data": {
"date": "2022-08-18",
"pipeline_name": "myhealth01",
"product_name": "Pre-Approval"
},
"Next": "LatestData",
"Type": "MockData"
},
"LatestData": {
"ExceptNext": "Health",
"Method": "GET",
"Next": "Health",
"Path": "console-pipeline/pipelines/{pipeline_name}/data/latest?sort_column=created_at",
"PathParameters": {
"pipeline_name": "$.outputs.Start.pipeline_name"
},
"Projection": {
"created_at": "$jmespath.created_at | date_format(@, '%Y-%m-%d %H:%M:%S.%f', '%Y-%m-%d')"
},
"Type": "InvokeProduct"
},
"Health": {
"Method": "GET",
"Next": "SaveData",
"Path": "code-health-checker/performance/metrics/products/{product_name}?start_date={start_date}&end_date={end_date}&status=failed",
"PathParameters": {
"end_date": "$jmespath.outputs.LatestData.response_payload.created_at || outputs.Start.date",
"product_name": "$.outputs.Start.product_name",
"start_date": "$jmespath.outputs.LatestData.response_payload.created_at || outputs.Start.date"
},
"Projection": {
"metrics": "$jmespath.metrics[*].{created_at: date_format(created_at, '%Y-%m-%dT%H:%M:%S.%f','%Y-%m-%d %H:%M:%S'), transaction_id: transaction_id}",
"next": "$.next_token"
},
"Type": "InvokeProduct"
},
"SaveData": {
"End": true,
"Method": "POST",
"Path": "console-pipeline/pipelines/{pipeline_name}/data",
"PathParameters": {
"pipeline_name": "$.outputs.Start.pipeline_name"
},
"RequestPayload": "$.outputs.Health.response_payload.metrics",
"Type": "InvokeProduct"
}
}
},
"trigger_schedule_expression": "rate(1 day)"
},
"dataset": {
"columns": [
{
"Name": "transaction_id",
"Type": "string"
},
{
"Name": "created_at",
"Type": "timestamp"
}
]
}
}
```
##### Response
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `verbose_name` | `string` | Pipeline Verbose Name |
| `description` | `string` | Pipeline Description |
| `job` | `object` | Pipeline Job |
| `definition`required | `object` | Job Definition |
| `StartAt`required | `string` | The first state |
| `States`required | `object` | Job States |
| `STATE_NAME` | `object` | Name of the State |
| `trigger_schedule_expression`required | `string` | Pipeline Trigger Schedule Expression |
| `triggers` | `array` | Triggers |
| `dataset` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `datasets` | `object` | Pipeline Datasets |
| `DATASET_NAME` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `product_name` | `string` | Staircase product name |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200`
`GET` `/pipelines`
#### Get All
`get_pipelines`
Get All Pipelines
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` | `string` query | `Product Name` | Product Name |
##### Response `200``application/json`
9 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `status` | `string` | Pipeline status`COMPLETED``FAILED``IN_PROGRESS` |
| `operation` | `string` | Pipeline operation`CREATE``DELETE``REVIEW``ROLLBACK``UPDATE``UPDATE_ROLLBACK` |
| `product_name` | `string` | Product name |
| `verbose_name` | `string` | Pipeline Verbose name |
| `job_name` | `string` | Pipeline Job name |
| `job_trigger_names` | `string[]` | Pipeline Job Trigger name |
| `created_at` | `string` | Pipeline create date |
| `updated_at` | `string` | Pipeline Success update date |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
### Pipeline
`GET` `/pipelines/{name}`
#### Get One
`get_pipeline`
Get pipeline
Retrieve pipeline information, such as:
- `status`
- `job_name`
- `job_trigger_names`
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
9 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `status` | `string` | Pipeline status`COMPLETED``FAILED``IN_PROGRESS` |
| `operation` | `string` | Pipeline operation`CREATE``DELETE``REVIEW``ROLLBACK``UPDATE``UPDATE_ROLLBACK` |
| `product_name` | `string` | Product name |
| `verbose_name` | `string` | Pipeline Verbose name |
| `job_name` | `string` | Pipeline Job name |
| `job_trigger_names` | `string[]` | Pipeline Job Trigger name |
| `created_at` | `string` | Pipeline create date |
| `updated_at` | `string` | Pipeline Success update date |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`DELETE` `/pipelines/{name}`
#### Delete One
`delete_pipeline`
Delete pipeline
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`GET` `/pipelines/{name}/config`
#### Get Config
`get_pipeline_config`
Retrieve Pipeline configuration.
Can and should be used to be able to Update Pipeline.
##### Response
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
7 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Pipeline Name |
| `verbose_name` | `string` | Pipeline Verbose Name |
| `description` | `string` | Pipeline Description |
| `job` | `object` | Pipeline Job |
| `definition`required | `object` | Job Definition |
| `StartAt`required | `string` | The first state |
| `States`required | `object` | Job States |
| `STATE_NAME` | `object` | Name of the State |
| `trigger_schedule_expression`required | `string` | Pipeline Trigger Schedule Expression |
| `triggers` | `array` | Triggers |
| `dataset` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `datasets` | `object` | Pipeline Datasets |
| `DATASET_NAME` | `object` | Pipeline Dataset |
| `columns`required | `array` | Columns |
| `calculated_columns` | `array` | Calculated Columns |
| `product_name` | `string` | Staircase product name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`404`
`GET` `/pipelines/{name}/datasets`
#### Get Datasets
`get_pipeline_datasets`
Retrieve Pipeline datasets
##### Response
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200``404`
### Pipeline Dashboards
`GET` `/pipelines/{name}/dashboards`
#### Get Dashboards
`get_pipeline_dashboards`
Get embedded link for pipeline dashboards. Going to return pipeline the links to all the dashboards.
Response includes:
- `id` - Dashboard ID
- `name` - Dashboard name
- `embedded_url` - Embedded URL. Links are QuickSight native with a temporary authentication token. So they can not be used for permanent share.
- `public_url` - Public URL. This is a permanent link that can be used to share Dashboard outside the Staircase.
It is good idea to use `embedded_link` inside a web page or web application that have authentication.
Important, `public_url` can be used without `API_KEY`. Please do not share it if Dashboard has sensitive data.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
4 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Dashboard ID |
| `name`required | `string` | Dashboard name |
| `embedded_url`required | `string` | Embedded URL |
| `public_url`required | `string` | Public URL |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
### Pipeline Data
`DELETE` `/pipelines/{name}/data`
#### Delete Data
`delete_data`
Delete Data from the Pipeline. After this operation Count Data should return zero.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`POST` `/pipelines/{name}/data`
#### Put Data
`put_data`
Put data
Put data will take an array of objects and push them into the pipeline. This endpoint is an alias of Pipeline Datasets Data / Put Data where `dataset_name` is `main`. Put Data endpoint does NOT override data. Instead, it is going to append data in the request payload with the data present in the pipeline. There is no predefined JSON schema for this operation. Objects that are in the arrays should be:
Show the rest
- Plain objects
- Should correspond to `dataset` columns definition of the Pipeline
Only data that is defined in the `dataset` columns will be saved in the pipeline.
Known limits are:
- Put data MAX array size 500 elements
Example of data being generated
```
curl --location --request POST '' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: '
```
#### Default values for columns
It is possible to specify default values for columns. Can be provider as a `key=value` in the query parameters For examplem having dataset specified as
```
{
"columns": [
{
"Name": "start_date",
"Type": "timestamp"
},
{
"Name": "stop_date",
"Type": "timestamp"
},
{
"Name": "transaction_id",
"Type": "string"
},
{
"Name": "time_spent_seconds",
"Type": "float"
},
{
"Name": "status",
"Type": "string"
},
{
"Name": "name",
"Type": "string"
},
{
"Name": "flow_name",
"Type": "string"
}
]
}
```
It is possible to set `flow_name` be `$.request_payload.pipeline_name` if it is null
```
{
"Method": "POST",
"End": true,
"Path": "console-pipeline/pipelines/{pipeline_name}/data?flow_name={flow_name}",
"PathParameters": {
"pipeline_name": "$.request_payload.pipeline_name",
"flow_name": "$.outputs.Start.flow_names[0]"
},
"RequestPayload": "$jmespath.outputs.response_payload.results",
"Type": "InvokeProduct"
}
```
#### Savings one row
Pipeline Put Data accepts an array of objects. To save one row it is possible to do one of following:
- Prepare data as an array of one object
- Use JMESPath Pipe expressions and arrays, for example `$jmespath.outputs.Pipelines.response_payload | [@]`
Example of SaveData, saving only one row to a Pipeline
```
{
"Save": {
"Type": "InvokeProduct",
"Method": "POST",
"Path": "console-pipeline/pipelines/{pipeline_name}/data",
"PathParameters": {
"pipeline_name": "$.request_payload.pipeline_name"
},
"RequestPayload": "$jmespath.outputs.Pipelines.response_payload | [@]",
"End": true
}
}
```
#### Returns
This operation usually returns:
```
{
"message": "ok"
}
```
This means data was accepted by the pipeline, but it does NOT guarantee data will be saved in the Dataset. If data was not saved to Dataset:
- most probably, there are problems with data format
- `timestamp` fields have wrong formats
- `int` fields be a string instead on integer
Important note, it may take 10-30 seconds for pipeline to consume and save data.
##### Request
PutDemoDataPutDemoDataWithMilliseconds
application/json Copy
```
[
{
"metric_number": 100,
"metric_status": "SUCCESS",
"date": "2022-08-15 23:23:23"
}
]
```
application/json Copy
```
[
{
"metric_number": 100,
"metric_status": "SUCCESS",
"date": "2022-08-15 23:23:23.123"
}
]
```
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
| `column_name` | `string` query | `Value` | Column default value |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`GET` `/pipelines/{name}/data/count`
#### Count Data
`count_data`
Get data count in the pipeline
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `count`required | `integer` | Count |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`GET` `/pipelines/{name}/data/latest`
#### Latest Data
`latest_data`
Get the latest data object from the pipeline. It is required to specify `sort_column` to allow data be sorted and latest be returned.
To avoid data duplicates and unnecessary operations, it is a good practice to use The Latest Data endpoint inside a Job before extracting data from a Staircase product. It is a good idea to filter data by date when extracting it from a Staircase product.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sort_column` required | `string` query | `date` | Sort Column |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
### Pipeline Dataset Data
`POST` `/pipelines/{name}/datasets/{dataset_name}/data`
#### Put Data
`put_dataset_data`
Put data
Put data to a dataset. Dataset should be defined in the Pipeline configuration in the `datasets`. Read Pipeline Put Data for more information.
##### Request
PutDemoDataPutDemoDataWithMilliseconds
application/json Copy
```
[
{
"metric_number": 100,
"metric_status": "SUCCESS",
"date": "2022-08-15 23:23:23"
}
]
```
application/json Copy
```
[
{
"metric_number": 100,
"metric_status": "SUCCESS",
"date": "2022-08-15 23:23:23.123"
}
]
```
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
| `dataset_name` required | `string` path | `ExampleDatasetName` | Dataset Name |
| `column_name` | `string` query | `Value` | Column default value |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`DELETE` `/pipelines/{name}/datasets/{dataset_name}/data`
#### Delete Data
`delete_dataset_data`
Delete Data from the Pipeline dataset. Read Pipeline Delete Data for more information.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
| `dataset_name` required | `string` path | `ExampleDatasetName` | Dataset Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`GET` `/pipelines/{name}/datasets/{dataset_name}/data/count`
#### Count Data
`count_dataset_data`
Get data count in the pipeline dataset. Read Pipeline Count Data for more information.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
| `dataset_name` required | `string` path | `ExampleDatasetName` | Dataset Name |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `count`required | `integer` | Count |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`GET` `/pipelines/{name}/datasets/{dataset_name}/data/latest`
#### Latest Data
`latest_dataset_data`
Get the latest data object from the pipeline dataset. Read Pipeline The Latest Data for more information.
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sort_column` required | `string` query | `date` | Sort Column |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
| `dataset_name` required | `string` path | `ExampleDatasetName` | Dataset Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
### Pipeline Debug
`POST` `/pipelines/{name}/run-job`
#### Run Pipeline Job
`run_pipeline_job`
Run Pipeline Job.
It is possible to run pipeline job with `pipeline_name`. `requestBody` is optional, but can contain data similar to `triggers` request_payload
##### Request
application/json Copy
```
{
"mp_host": "marketplace.staircaseapi.com",
"mp_key": "API_KEY",
"comply_auth": "TOKEN",
"comply_host": "compliance-auth.comply-authentication.staircaseapi.com"
}
```
##### Response
200400403
application/json Copy Success
```
{
"execution_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
"job_name": "job_name"
}
```
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `200``application/json`
2 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `execution_id` | `string (ulid)` | Job Execution IDExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `job_name` | `string` | Job Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`GET` `/pipelines/{name}/error-logs`
#### Get Error Logs
`get_pipeline_error-logs`
Retrieve Pipeline Error Logs
##### Response
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200``404`
### Account
`GET` `/quicksight`
#### Status
`quicksight_get`
Get QuickSight status
Expected response
```
{
"status": "ACCOUNT_CREATED"
}
```
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | QuickSight Status |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`404`
`POST` `/quicksight`
#### Activate
`quicksight_activate`
Activate QuickSight account
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
`DELETE` `/quicksight`
#### Delete
`quicksight_delete`
Delete QuickSight account
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
### Chat
`POST` `/service-message`
#### Send message to Chat
`sendMessage`
Chat
This endpoint allows to send a message to user in Chat product.
##### Request
application/json Copy
```
{
"connection_id": "WbETDfY8IAMCE8A=",
"message_id": "b2QlQarRO8"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `connection_id` | `string` | The identifier of connection |
| `message_id` | `string` | The message identifier |
##### Response `201``application/json`
2 fields
Assistant created
| Field | Type | Description |
| --- | --- | --- |
| `connection_id` | `string` | The identifier of connection |
| `message_id` | `string` | The message identifier |
##### Other responses
`400``403``404`
### Setup
`POST` `/sign_in`
#### Sign In
`sign-in`
Sign in.
Sign in the credentials
##### Request
application/json Copy An example of a payload.
```
{
"email": "john.doe@company.com",
"password": "XXXXX"
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"id_token": "xxxxxx",
"refresh_token": "",
"token_type": "yyyyyy"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
3 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `id_token` | `string` | The ID token. |
| `refresh_token` | `string` | The refresh token. |
| `token_type` | `string` | The token type. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
### Proxy
`POST` `/trust_score`
#### Get Trust Score
`get_configuration`
This endpoint serves as a proxy to the Get Trust Score api that allows bypassing api_key authorization, yet, is limited in domains that can access it.
##### Request
application/json Copy
```
{
"phone_number": "8167434789",
"transaction_id": "01H3YA4JVJ3ZF3M41NXK9PA27T"
}
```
##### Response
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `phone_number`required | `string` | Valid Phone Number |
| `birth_date` | `string` | Should follow YYYY-MM-DD format. |
| `transaction_id`required | `string` | Transaction ID |
| `console_configuration_id` | `string` | Console app configuration ID |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Invocation ID |
##### Other responses
`403``422`
`POST` `/identity`
#### Get Identity
`get_identity`
This endpoint serves as a proxy to the Get Identity api that allows bypassing api_key authorization, yet, is limited in domains that can access it.
##### Request
application/json Copy
```
{
"phone_number": "8167434789",
"birth_date": "1990-01-01",
"transaction_id": "01H3YA4JVJ3ZF3M41NXK9PA27T"
}
```
##### Response
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `phone_number`required | `string` | Valid Phone Number |
| `birth_date`required | `string` | Should follow YYYY-MM-DD format. |
| `transaction_id`required | `string` | Transaction ID |
| `console_configuration_id` | `string` | Console app configuration ID |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Invocation ID |
##### Other responses
`403``422`
`POST` `/{api_name}/invocations/{id}`
#### Get Invocation Status
`get_invocation_status`
This endpoint serves as a proxy to the Get Invocation Status of Identity apis, referenced by the api_name and identifer of the invocation. `api_name` should be one of ['trust_score', 'identity'].
##### Response
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `api_name` required | `string` path | `trust_score` | Identity api name |
| `id` required | `string` path | `01H3FP37TVHBY7R9C1013BDGM5` | Invocation ID |
##### Other responses
`200``403``422`
### Connection Proxy
`POST` `/vendors/{vendor_name}/flows/{flow_name}/jobs`
#### Invoke Connection Flow
`invoke_connection_flow`
This endpoint serves as a proxy to the Invoke Partner Flow api that allows bypassing api_key authorization, yet, is limited in domains that can access it. List of flows that can be invoked with this proxy is also limited and pre-defined. Please, refer to documentation of original endpoint for the request and response schemas.
##### Request
application/json Copy
```
{
"transaction_id": "01F7S0N7CQ31DZQYVSVPN66GNK",
"callback_url": "https://webhook.site/2c40525f-69ec-485f-a79a-7256406e8da4",
"request_payload": {}
}
```
##### Response
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `vendor_name` required | `string` path | `prove` | Vendor name |
| `flow_name` required | `string` path | `get_trust_score` | Flow name |
##### Response `202``application/json`
2 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `job_id` | `string` | Invocation ID |
| `job_status` | `string` | Job status |
##### Other responses
`403``422`
`POST` `/vendors/{vendor_name}/flows/{flow_name}/jobs/{job_id}`
#### Get Invocation Status
`get_invocation_status`
This endpoint serves as a proxy to the Retrieve Flow Execution Status. Please, refer to original documentation for request and response schemas.
##### Response
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `vendor_name` required | `string` path | `prove` | Vendor name |
| `flow_name` required | `string` path | `get_trust_score` | Flow name |
| `job_id` required | `string (uuid)` path | `7c668252-d2ba-job-id-896d-1f73236287d9` | Job invocation ID |
##### Other responses
`200``403``422`
### Datalake Data
`POST` `/datalakes/{name}/data`
#### Put Data
`put_datalake_data`
Put data
Put data will the data from valid Staircase collection.
Known limits are:
- Put data MAX array size 500 elements
Important note, it may take 10-30 seconds for pipeline to consume and save data.
##### Request
application/json Copy
```
[
{
"metric_number": 100,
"metric_status": "SUCCESS",
"date": "2022-08-15 23:23:23"
}
]
```
##### Response
400403
application/json Copy Bad Request
```
{
"message": "Bad Request!"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `pipeline_name` | Pipeline Name |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Other responses
`200``404`
## Errors
`400``401``403``404``422``500``502`
## Notes
The catalogue records no narrative row for this slot. What appears above is read from the recorded build documentation and from the operation set. The component inventories — several hundred records naming each component, its properties and its content-system shape — are internal build material and are not published.
## More in Distribution
- Previous product: Access
- Next product: Environment
---
# Environment
# Environment
Creating, configuring, cost-tracking, budgeting and tearing down a dedicated cloud environment over HTTP.
An environment here is a whole cloud account, not a namespace: its own domain, its own certificates, its own API key, its own stack set. It is created, configured, metered against a budget and destroyed through calls.
Teardown is a first-class path with scripted removal of stacks, storage and identity, rather than an operational runbook someone follows by hand.
## How it works
Cost attribution reaches down to individual model conversations and up to a per-environment budget. Metering at that granularity is what makes a budget enforceable instead of advisory — a budget that can only be checked after the invoice arrives cannot stop anything.
A configuration check returns a vector of policy answers rather than a pass or fail, so an environment that is out of policy names which control it fell out of.
## Operations
### Activate Key
`POST` `/activate-key`
#### Activate Key for Environment
`activateKey`
Activate key used to activate a key for being used in the environment.
##### Request
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string` | X-api-key to be activated in the environmentExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `200``application/json`
3 fields
Key activated.
| Field | Type | Description |
| --- | --- | --- |
| `fqdn`required | `string` | Fully qualified domain name of the environment where the key was activated. |
| `status`required | `string` | Status of the key activation. |
| `message`required | `string` | Message about the key activation. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error`required | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error`required | `string` | Error message. |
##### Response `500``application/json`
1 fields
Key Activation error
| Field | Type | Description |
| --- | --- | --- |
| `error`required | `string` | Error message. |
##### Other responses
`403`
### Budgets
`PUT` `/budgets/{fqdn}`
#### Update environment budget
`updateBudget`
This API allows the Staircase Finance team to update the budget of a given environment.
##### Request
application/json Copy
```
{
"products": [
{
"product_name": "Language",
"monthly_budget": 1500
},
{
"product_name": "Batch",
"monthly_budget": 750
},
{
"product_name": "Datalake",
"monthly_budget": 750
}
]
}
```
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY received via email upon account creation |
| `fqdn` required | `string` path | `example.staircaseapi.com` | Environment fully qualified domain name. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `products`required | `object[]` | List of products and their monthly budget. |
| `product_name`required | `string` | Name of the product.Example `Environment` |
| `monthly_budget`required | `number` | Monthly budget for the product.Example `1000` |
##### Response `201``application/json`
3 fields
Environment creation In-progress.
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Fully qualified domain name of the environment. |
| `monthly_budget`required | `object` | Monthly budget for the environment. |
| `products` | `object[]` | List of products and their monthly budget. |
| `product_name`required | `string` | Name of the product.Example `Environment` |
| `monthly_budget`required | `number` | Monthly budget for the product.Example `1000` |
| `last_update_datetime`required | `string` | Last update time stamp. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`PUT` `/budgets`
#### Create or update budget for products owned by team
`createOrUpdateTeamBudget`
Create or update team budget
This API manages and monitors daily spending on products for each company by storing budget information and summing all related spending per company and product. If spending exceeds the budget, it sends alerts to the company’s Slack #alerts-negative channel for each additional dollar spent.
##### Request
application/json Copy
```
{
"budget_per_day": 25,
"product_identifier": "c20994b0-be01-4421-a075-8dcea035d155",
"company_identifier": "01G52C9RCP0Q5C6JYEPE4487VV"
}
```
##### Response
200400
application/json Copy Environment creation In-progress.
```
{
"budget_per_day": 25,
"product_identifier": "c20994b0-be01-4421-a075-8dcea035d155",
"company_identifier": "01G52C9RCP0Q5C6JYEPE4487VV"
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY received via email upon account creation |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `budget_per_day`required | `number` | US dollars per day.Example `25` |
| `product_identifier`required | `string` | Product identifier.Example `c20994b0-be01-4421-a075-8dcea035d155` |
| `company_identifier`required | `string` | Company identifier fromExample `01G52C9RCP0Q5C6JYEPE4487VV` |
##### Response `200``application/json`
3 fields
Environment creation In-progress.
| Field | Type | Description |
| --- | --- | --- |
| `budget_per_day`required | `number` | US dollars per day.Example `25` |
| `product_identifier`required | `string` | Product identifier.Example `c20994b0-be01-4421-a075-8dcea035d155` |
| `company_identifier`required | `string` | Company identifier fromExample `01G52C9RCP0Q5C6JYEPE4487VV` |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
### Costs
`GET` `/costs`
#### Retrieve product costs
`getProductCosts`
Retrieve the detailed product costs across the organization.
Due to the monthly billing cycle, the values will change until the end of the month is reached, and the final adjustments are applied.
The authorization access token for using this service can be obtained from Comply Authentication
##### Response
200400 application/json400 text/html
application/json Copy Response body with the detailed costs of a given product across all environments.
```
{
"total_cost": "$ 1785.4194 USD",
"costs_unit": "USD",
"total_cost_raw": 1785.4194,
"product_name": "Test",
"environments_count": 330,
"average_environment_cost": 5.4104,
"costs_by_environment": [
{
"costs": 146.4983,
"organization_id": "01G5XXXXXXXXXX93E41X70MXS",
"environment_domain": "my-subdomain.staircaseapi.com"
}
],
"costs_by_service": [
{
"aws_service": "Amazon EC2 Container Registry (ECR)",
"cost": 654.9967
},
{
"aws_service": "AWS Key Management Service",
"cost": 318.5916
},
{
"aws_service": "Amazon Simple Storage Service",
"cost": 13.0348
},
{
"aws_service": "AWS Lambda",
"cost": 7.3645
},
{
"aws_service": "AWS WAF",
"cost": 5.8065
},
{
"aws_service": "Amazon DynamoDB",
"cost": 1.9304
},
{
"aws_service": "AmazonCloudWatch",
"cost": 0.6591
},
{
"aws_service": "Amazon Simple Queue Service",
"cost": 0.5514
},
{
"aws_service": "CodeBuild",
"cost": 0
}
],
"costs_by_period": [
{
"time_period": "2022-08-01-2022-08-02",
"cost": 70.3507
},
{
"time_period": "2022-08-02-2022-08-03",
"cost": 76.8517
}
]
}
```
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
| `product_name` required | `string` query | `Environment` | Product name |
| `start_date` required | `string` query | `2022-01-01` | start date for the time range |
| `end_date` required | `string` query | `2022-01-31` | end date for the time range |
##### Response `200``application/json`
8 fields
Response body with the detailed costs of a given product across all environments.
| Field | Type | Description |
| --- | --- | --- |
| `total_costs`required | `string` | Formatted total costs for the given product name. |
| `costs_unit`required | `string` | Unit for the costs values. |
| `total_costs_raw`required | `number` | Total costs for the given product name. |
| `environments_count`required | `number` | Number of environments in which the product is deployed. |
| `average_environment_cost`required | `number` | Average cost per environments. |
| `costs_by_environment`required | `object[]` | List of Product costs per environment |
| `product_by_environment_costs` | `object` | Data object containing the Product costs per environment |
| `environment_domain` | `string` | Domain of the environment |
| `costs` | `number` | Product costs of the environment |
| `organization_id` | `string` | Domain of the environment |
| `costs_by_service`required | `object` | Product costs by AWS service |
| `costs_by_period` | `object` | Product costs by day |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/environment-costs/{api_key}`
#### Retrieve environment costs
`getEnvironmentCosts`
Retrieve environment costs.
When resource_details is set to true, the output will show the costs detailed by service instead of the component.
Due to the monthly billing cycle, the values will change until the end of the month is reached, and the final adjustments are applied.
This service only provides data for last 14 days. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
| `api_key` required | `string` path | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for the environment to query |
| `start_date` required | `string` query | `2022-01-01` | start date for the time range |
| `end_date` required | `string` query | `2022-01-31` | end date for the time range |
| `resource_details` | `boolean` query | `true` | If enabled it will show the Environment resources usage detail, resource details cannot be used with more that 14 days old dates. |
##### Response `200``application/json`
4 fields
Response body with the list of stacks deployed in a given environment.
| Field | Type | Description |
| --- | --- | --- |
| `unit`required | `string` | Currency |
| `total_cost`required | `string` | Total cost for the given environment. |
| `time_range`required | `object` | Time range queried. |
| `start_date`required | `string` | Start date for the time range queried |
| `end_date`required | `string` | End date for the time range queried |
| `usage_details`required | `object[]` | Usage details of the environment by stack name. |
| `service`required | `string` | Name of the resource service. |
| `cost`required | `string` | Total cost generated by the resource. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
### EnvironmentCosts
`POST` `/costs`
#### Save Costs
`save-costs`
For tracking non AWS related costs.
Use this API for reporting usage of external services that are not tracked by AWS. For example, this API is used by the Bot product to report the price of conversation for specific bot.
##### Request
application/json Copy
```
{
"usage": 3,
"name": "Personal Identity Collector",
"invocation_id": "1234567890"
}
```
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `usage`required | `number` | Usage of the external service, in US Cents.Example `100` |
| `name`required | `string` | Name of the external service.Example `Personal Identity Collector` |
| `invocation_id` | `string` | Unique identifier for the invocation of the external service. |
##### Response `200``application/json`
1 fields
Response body with confirmation of the saved costs.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Confirmation message. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
### Environment
`POST` `/environment`
#### Create Environment
`createEnvironment`
Create environment
This service allows you to create a staircase environment for with a given subdomain.
You can also include a callback URL with an optional payload to get notified automatically after your environment creation is finished;
After the environment is created it is subscribed to Environment and Deploy products automatically.
- Callback payload request example:
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subdomain": "my-env",
"organization_id": "26d4253f8509"
"callback_url": "",
"callback_payload": {"callback_id":"identifier_callback"}
}
```
- Callback payload response example:
```
{
"environment_status": "ACTIVE",
"environment_fqdn": "my-env.staircaseapi.com",
"message": "Environment ready to use",
"callback_payload": {"callback_id":"identifier_callback"}
}
```
##### Request
application/json Copy
```
{
"subdomain": "mysubdomain",
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"organization_id": "26d4253f8509",
"callback_url": "https://mycallbak_url.com/callback_url",
"callback_payload": {
"callback_id": "identifier_callback"
}
}
```
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY received via email upon account creation |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `subdomain`required | `string` | Subdomain for the New Staircase environment.Example `marketplace` |
| `api_key`required | `string (uuid)` | API-KEY received via email upon account creationExample `` |
| `organization_id` | `string` | Organization ID to which the account belongs toExample `b665gncdb891` |
| `callback_url` | `string` | Callback URL POST endpoint to be called upon environment creation completionExample `https://mycallbak_url.com/callback_url` |
| `callback_payload` | `object` | User defined payload to be sent to the callback URL suppliedExample `{'callback_id':'identifier_callback'}` |
##### Response `201``application/json`
2 fields
Environment creation In-progress.
| Field | Type | Description |
| --- | --- | --- |
| `staircase_environment`required | `object` | Staircase Environment creation status. |
| `api_key`required | `string` | Unique identifier for the environment. |
| `status_url`required | `string` | URL for checking the status while it's not Active. |
| `status`required | `string` | Status of the environment creation. |
| `message`required | `string` | Status description message. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`PUT` `/environment`
#### Update Environment Data
`updateEnvironmentData`
This service allows you to update the environment data such as organization ID
##### Request
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"organization_id": "26d4253f8509"
}
```
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY received via email upon account creation |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string (uuid)` | API-KEY received via email upon account creationExample `` |
| `organization_id`required | `string` | Organization ID to which the account belongs toExample `b665gncdb891` |
##### Response `200``application/json`
2 fields
Environment Data Update.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Status description message. |
| `status`required | `string` | Status of the operation executed |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`DELETE` `/environment`
#### Disable Environment
`disableEnvironment`
This service allows you to disable a given environment. Disabling an environment will delete all the resources in it and the environment will not be recoverable The authorization access token for using this service can be obtained from Comply Authentication The token requires an admin level permission
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Account-key received via email upon account creation. |
| `environment_fqdn` required | `string` query | `my-env.staircaseapi.com` | Fully qualified domain name of the staircase environment. |
##### Response `200``application/json`
2 fields
Environment Data Update.
| Field | Type | Description |
| --- | --- | --- |
| `environment_fqdn`required | `string` | Fully qualified domain name of the environment. |
| `organization_id`required | `string` | Organization ID of the queried environment. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/environment`
#### Get Environment Data
`getEnvironmentData`
This service allows you to retrieve the environment data such as organization ID
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Account-key received via email upon account creation. |
| `environment_fqdn` required | `string` query | `my-env.staircaseapi.com` | Fully qualified domain name of the staircase environment. |
##### Response `200``application/json`
5 fields
Environment Data Update.
| Field | Type | Description |
| --- | --- | --- |
| `environment_fqdn`required | `string` | Fully qualified domain name of the environment. |
| `organization_id`required | `string` | Organization ID of the queried environment. |
| `environment_owner`required | `string` | Owner email of the queried environment. |
| `company_name`required | `string` | Company name of queried environment. |
| `last_updated_at`required | `string` | When environment was updated. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`DELETE` `/environment/delete`
#### Clean Environment
`disableEnvironment`
This service allows you to clean a given environment. Cleaning an environment will delete all the resources in it and the environment will not be recoverable
##### Request
application/json Copy
```
{
"target_account_id": "123456789033"
}
```
##### Response
application/json Copy Request data invalid
```
{
"message": "target_account_id must be provided."
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `target_account_id`required | `string` | AWS account ID of the environment to be cleaned. The account ID must be a 12-digit number within Staircase organization. |
| `callback_url` | `string (uri)` | URL to be called when the cleaning process is complete. The URL must be accessible from the internet.s |
| `resources_to_retain` | `object` | Object specifying arrays of S3 and Glue resources to be retained during cleanup. Each array contains objects representing individual resources. A report will be generated post-cleanup detailing retained and removed resources. In case of errors in retaining a specified resource, the user will be notified for manual intervention. |
| `S3` | `object[]` | Array of objects, each representing an S3 bucket name to be retained. |
| `bucket_name`required | `string` | Name of the S3 bucket to be retained. |
| `Glue` | `object[]` | Array of objects, each representing a Glue resource to be retained. |
| `database_name`required | `string` | Name of the Glue database to be retained. |
| `IAMUser` | `string` | IAM User to be retained. |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `job_id`required | `string` | ID of the cleaning job.Example `01GXQZV8M1V57GEZHK29SR1J3J` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`POST` `/`
#### Add region
`addRegion`
This service allows you to configure new region is this environment, so it will be ready to get Staircase bundles deployed in it WAF distribution will be created. The distribution ID will be available inside the environment token data. api.subdomain.staircaseapi.com custom API GW domain name will be created. {region_name}.subdomain.staircaseapi.com custom API GW domain name will be created. Route53 failover configuration will be created for api.subdomain.staircaseapi.com and used for the health checks managed by the Environment product. Route53 us-east-1.domain.com to direct to API Gateway on us-east-1
##### Request
application/json Copy
```
{
"region_name": "us-east-2"
}
```
##### Response
200400
application/json Copy Ok.
```
{
"message": "Region added"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `region_name`required | `string` | Region name`us-east-2``us-west-1``us-west-2`Example `us-east-2` |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | message |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/stacks/{api_key}`
#### Retrieve environment products
`getProductsDeployed`
Retrieve the environment products
Get environment components Fetch list of deployed components in a given environment. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
| `api_key` required | `string` path | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API-KEY |
##### Response `200``application/json`
1 fields
Response body with the list of stacks deployed in a given environment.
| Field | Type | Description |
| --- | --- | --- |
| `stacks`required | `object[]` | List of stacks in the environment |
| `stack_name` | `string` | Name of the stack deployed. |
| `stack_status`required | `string` | Current status of the stack. |
| `created_at`required | `string` | Creation time stamp. |
| `last_updated_at`required | `string` | Last update time stamp. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
### Hello
`POST` `/hello-world`
#### Hello
`execute_query`
Hello World
Dummy hello world endpoint
##### Response
application/json Copy Ok.
```
{
"message": "ok"
}
```
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Hello message.Example `ok` |
### Products
`GET` `/product-deployments`
#### Retrieve products deployments
`getProductDeployments`
Retrieve product deployments
Retrieve all the environments in which the product is deployed with their Health API KEY. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
| `base_path` required | `string` query | `code-tester` | The base path of the product you want to query |
##### Response `200``application/json`
1 fields
Response body with the list of environments in which the product is deployed.
| Field | Type | Description |
| --- | --- | --- |
| `environments`required | `object[]` | List of environments with the base path given present. |
| `domain_name`required | `string` | Name of the stack. |
| `api_key`required | `string` | Health API KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
### EnvironmentManager
`DELETE` `/products`
#### Delete deployed product
`deleteProductServices`
This service triggers the deletion of a given product, if no specific services are given all the services deployed for the given product name will be deleted. Deletion of a given service or services will remove the resources and will cause loss of data. Admin level permissions are necessary for deleting products from a Staircase environment, unless you are the owner of the environment. The authorization access token for using this service can be obtained from Comply Authentication
##### Request
application/json Copy
```
{
"product_name": "Test",
"services": [
{
"service_name": "service-code-tester"
}
]
}
```
##### Response
201400
application/json Copy Environment creation In-progress.
```
[
{
"status": "SUBMITTED"
}
]
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `string` | Name of the product to be deletedExample `Test` |
| `services` | `object[]` | List of services to be deleted |
| `service_name`required | `string` | Name of the service to be deletedExample `service-code-tester` |
##### Response `201``application/json`
1 fields
Environment creation In-progress.
| Field | Type | Description |
| --- | --- | --- |
| `status`required | `string` | Status of the deletion.Example `SUBMITTED` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Environment creation failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/products`
#### Get Deployed Products
`getDeployedProducts`
Retrieve the products deployed in the environment
Get deployed products Retrieves a list of the products deployed in the environment with their respective components. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
200400
application/json Copy Response body with the list of products and services deployed in the staircase environment.
```
[
[
{
"product_name": "Environment",
"services": [
{
"service_name": "environment-manager",
"status": "UPDATED"
},
{
"service_name": "environment-administrator",
"status": "UPDATED"
}
]
}
]
]
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
##### Response `200``application/json`
2 fields
Response body with the list of products and services deployed in the staircase environment.
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `string` | Product Name deployed in the staircase environment. |
| `services`required | `object[]` | List of services attached to the product. |
| `status`required | `string` | Deployment status of the service. |
| `service_name`required | `string` | Name of the service deployed. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Product not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/products/{product_name}`
#### Get Deployed Product
`getDeployedProductServices`
Retrieve the details of a product deployed in the environment
Get deployed products Retrieves the list of services deployed containing status and service name for the product name given, as log as it is deployed in the staircase environment. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
200400
application/json Copy Response body with the list of services deployed in the staircase environment for the provided product name.
```
[
[
{
"service_name": "environment-manager",
"status": "UPDATED"
},
{
"service_name": "environment-administrator",
"status": "UPDATED"
}
]
]
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
| `product_name` required | `string` path | `Environment` | Name of the product to query |
##### Response `200``application/json`
2 fields
Response body with the list of services deployed in the staircase environment for the provided product name.
| Field | Type | Description |
| --- | --- | --- |
| `status`required | `string` | Deployment status of the service. |
| `service_name`required | `string` | Name of the service deployed. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/service-key`
#### Get Service Key
`get-service-key`
Get service key
Environment service API-KEY can be used for retrieving telemetry data. Health product accepts it as X-API-KEY header, enabling products and teams to querying metrics for products deployed in the environment. The authorization access token for using this service can be obtained from Comply Authentication
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
##### Response `200``application/json`
1 fields
Response body with the environment status and, environment details
| Field | Type | Description |
| --- | --- | --- |
| `service_key`required | `string` | UUID value of the service key. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Service key error.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/budgets`
#### Get Budgets
`get-budgets-list`
List of currently applied budgets for this environment.
List of currently applied budgets for this environment. It calculates only for resources tagged with "sc:product:name" tag with this value. Budget is always monthly.
##### Response `200``application/json`
1 fields
Response body with the environment current budgets per product.
| Field | Type | Description |
| --- | --- | --- |
| `budgets` | `object[]` | List of budgets per product. |
| `product`required | `string` | Product name. It calculates only for resources tagged with "sc:product:name" tag with this value. |
| `amount`required | `string` | Budget amount in US Dollars per month. |
`PATCH` `/budgets`
#### Update Budgets
`update-budgets`
Update the thresholds for the budgets.
Update the threshold for specific products.
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Response `200``application/json`
1 fields
Response body with the environment updated budgets.
| Field | Type | Description |
| --- | --- | --- |
| `budgets` | `object[]` | List of budgets per product. |
| `product`required | `string` | Product name. It calculates only for resources tagged with "sc:product:name" tag with this value. |
| `amount`required | `string` | Budget amount in US Dollars per month. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
### Reports
`GET` `/reports`
#### Get Cost Reports
`getCostReports`
Provides reports about AWS costs produced by Staircase Products deployed to Staircase Environments.
The unit type of the all costs in reports is presented in cents by default. You can change it to "USD" by passing it as a query parameter `costs_unit_type`.
If start_date and end_date are not specified, the default date range is the last 30 days.
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `start_date` | `string` query | `2023-01-01` | Start date. |
| `end_date` | `string` query | `2023-02-01` | End date. |
| `granularity` | `string` query | `DAILY` | Granularity. |
| `customer_company_name` | `string` query | `Bank Of America` | Customer company name. Case insensitive. |
| `staircase_team` | `string` query | `Cerf` | Staircase team name. Case insensitive. |
| `costs_unit_type` | `string` query | `USD` | Costs unit type. If not specified, the default unit type is CENT. |
##### Response `200``application/json`
5 fields
Response body
| Field | Type | Description |
| --- | --- | --- |
| `date_range`required | `object` | The date range for which the report is applicable. |
| `start`required | `string` | The start date of the range in YYYY-MM-DD format. |
| `end`required | `string` | The end date of the range in YYYY-MM-DD format. |
| `costs_unit_type`required | `string` | The unit type of costs in reports.`CENT``USD`Example `USD` |
| `granularity` | `string` | The dates granularity of the report.`DAILY``MONTHLY``NONE`Example `DAILY` |
| `products`required | `object[]` | A list of Staircase products included in the report. Data bundles are united to a single "Data Bundles" product. |
| `product_name` | `string` | The name of the product. |
| `reports`required | `object[]` | A collection of cost reports, each corresponding to a single time period. If 'granularity' query parameter is not NONE, it might contain more than one report object. |
| `type`required | `string` | The type of report.`COSTS_PER_ENVIRONMENT_PER_PRODUCT` |
| `date_range` | `object` | The date range for which the report is applicable. |
| `start`required | `string` | The start date of the range in YYYY-MM-DD format. |
| `end`required | `string` | The end date of the range in YYYY-MM-DD format. |
| `result`required | `object[]` | An array of results, each representing a different environment. |
| `environment`required | `string` | The name or identifier of the environment. |
| `total_cost`required | `integer` | The total cost associated with this environment. |
| `costs_per_product_sum`required | `integer` | The sum of costs broken down per product. |
| `costs_per_product`required | `object` | A breakdown of costs per product. |
| `unknown_product_cost`required | `integer` | Costs associated with unknown or unclassified products. |
| `staircase_team`required | `string` | The name of the Staircase team owning the environment. |
| `customer_company_name`required | `string` | The name of the customer company owning the environment. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
### Configurations
`POST` `/update-configurations`
#### Update configurations
`update-configurations`
Update Configurations
Update environment configurations validates the latest configurations of the environment and if they are not up-to-date it updates them.
##### Request
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string (uuid)` | API-KEY received via email upon account creationExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `201``application/json`
1 fields
Environment creation In-progress.
| Field | Type | Description |
| --- | --- | --- |
| `staircase_environment` | `object` | Staircase Environment creation status. |
| `status`required | `string` | Status of the environment configurations update process.`UPDATED``UPDATE_FAILED``UPDATING` |
| `message`required | `string` | Information message for the given status |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Environment creation failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/get-configurations/{api_key}`
#### Get configurations
`get-configurations`
Get the environment configurations Fetch the status of the environment configurations.
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Authorization token, obtained through comply service. |
| `api_key` required | `string` path | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API-KEY |
##### Response `200``application/json`
11 fields
Response body with the environment status and, environment details
| Field | Type | Description |
| --- | --- | --- |
| `MFA_Enabled`required | `string` | Status of the user with MFA_Enabled configuration.`MISSING``OK` |
| `Login_Restricted`required | `string` | Status of the AWS console login restriction.`MISSING``OK` |
| `Main_Certificate`required | `string` | Status of the Main Certificate configuration.`MISSING``OK` |
| `Wild_Certificate`required | `string` | Status of the Wild Certificate configuration.`MISSING``OK` |
| `Email_Domain`required | `string` | Status of the Email Domain configuration.`MISSING``OK` |
| `DKIM_Verification`required | `string` | Status of the DKIM verification.`MISSING``OK` |
| `MX_Records`required | `string` | Status of the MX DNS records.`MISSING``OK` |
| `API_Gateway`required | `string` | Status of the API GW Configuration.`MISSING``OK` |
| `Health_Service_Key`required | `string` | Status of the Health service API key configuration.`MISSING``OK` |
| `VPC_Flow_Logs` | `string` | Status of the VPC Flow Log configuration.`MISSING``OK` |
| `CloudFront_Distribution`required | `string` | Status of the CloudFront distribution configuration.`MISSING``OK` |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Server error.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
### Status
`GET` `/environment/delete/{id}`
#### Retrieve Cleaning Status
`getCleaningStatus`
Foo
##### Response
400404
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Cleaning invocation was not found.
```
{
"status": "NOT_FOUND"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `id` required | `string` path | `490kokf3-aa93-409f-b4e7-756e019d83f5` | The cleaning invocation ID. |
##### Response `200``application/json`
2 fields
Cleaning job invocation status.
| Field | Type | Description |
| --- | --- | --- |
| `status`required | `string` | Status of the cleaning job invocation.`FAILED``IN_PROGRESS``NOT_FOUND``RUNNING``SUCCEEDED` |
| `logs`required | `string` | Logs of the cleaning invocation. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting an X-API-KEY. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Cleaning invocation was not found.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the cleaning job.`NOT_FOUND` |
### Environment Creator
`POST` `/vendors/staircase/flows/env-create/jobs`
#### Invoke Create Environment Flow
`invokeCreateEnvironmentFlow`
This endpoint allows launching Create Environment Flow.
It is an asynchronous job, so response contains `job_id`, that allows to track the job's execution here. Result of the job will be sent to the `callback_url` specified in the appropriate field. If job finishes successfully, `job_status` will be "Completed"; `response_payload` will contain the `api_key`, `domain`, `subdomain` and `organization_id`, and it will look like this:
Show the rest
```
{
"job_id": "e26ffa3d-4ae6-4582-8982-5d61f8a75c54",
"job_status": "Completed",
"transaction_id": "01F7S0N7CQ31DZQYVSVPN66GNK",
"request_collection_id": "01F7S0X38J6R41HW279D8YP8KJ",
"response_collection_id": "01F7S0YSQPGW9WC51378PR7TM3",
"response_payload": {
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain": "organization-a1b2c3d4e5f6",
"subdomain": "organization-a1b2c3d4e5f6.staircaseapi.com",
"organization_id": "4321-4321-4321-4321-4321"
}
}
```
If job fails to complete, `job_status` will be "Failed" and `response_payload` will contain detailed information about failed job (`Error` and `Cause` fields), and will look like this:
```
{
"job_id": "98da2ca6-8fbb-4f00-bde9-91f8b33712f2",
"job_status": "Failed",
"transaction_id": "01FYRX3TTMKSR6XG070GA3MG17",
"request_collection_id": null,
"response_collection_id": null,
"response_payload": {
"Error": "CallVendorError",
"Cause": {
"errorMessage": {
"message": "A company_organization with company \"X\" and organization \"X-org-1\" already exists."
},
"errorType": "CallVendorError",
"requestId": "77a1db7e-12d4-42f3-887e-82387a2ca8cd"
}
},
"status_code": null
}
```
For testing, you can use webhook.site service. With this, you instantly get a unique, random URL that you can put into the `callback_url` field and use it to receive HTTP requests.
##### Request
application/json Copy
```
{
"transaction_id": "01F7S0N7CQ31DZQYVSVPN66GNK",
"callback_url": "https://webhook.site/cc87117a-36ee-4b8b-b098-e9cf209821a2",
"request_payload": {
"organization_name": "Org-1",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@domain.com"
}
}
```
##### Response
202400
application/json Copy Request accepted
```
{
"job_id": "160701d5-a034-41db-aade-26e4134ac8bb",
"job_status": "Started"
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` query | `environment-creator` | This parameter is required to be `environment-creator`. Anything else would cause a failure |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transaction ID |
| `request_collection_id` | `string` | Request collection ID |
| `response_collection_id` | `string` | Response collection ID |
| `callback_url`required | `string (uri)` | Destination URL on which final result of the flow execution will be sent |
| `request_payload`required | `object` | Data that have to passed into the flow |
| `organization_name`required | `string` | Name of the Organization that Environment will belong to |
| `first_name`required | `string` | First Name of the owner of Account that Environment will belong to |
| `last_name`required | `string` | Last Name of the owner of Account that Environment will belong to |
| `email`required | `string` | Email of the owner of Account that Environment will belong to |
##### Response `202``application/json`
2 fields
Request accepted
| Field | Type | Description |
| --- | --- | --- |
| `job_id` | `string` | Execution ID |
| `job_status` | `string` | Execution status |
##### Response `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Request forbidden -- authorization will not help |
| `url` | `string (url)` | Indicates at which url the error occurs |
##### Response `404``application/json`
1 fields
Partner or flow not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Nothing matches the given URI |
`GET` `/vendors/staircase/flows/env-create/jobs/{job_id}`
#### Retrieve Create Environment Flow Execution Status
`retrieveCreateEnvironmentFlowExecutionStatus`
Retrieve flow execution status of Create Environment flow
This endpoint allows getting status of the Create Environment Flow.
##### Response
200400
application/json Copy Execution status successfully retrieved
```
{
"status": "FAILED",
"executed_events": [
"GetCredentials",
"Wait1",
"Wait2"
],
"last_event": "Wait2",
"details": [
{
"event_id": 2,
"event_type": "stateEnteredEventDetails",
"event_name": "GetCredentials",
"timestamp": "2021-06-10 23:25:27.661000+03:00",
"previous_event_id": 0,
"input_details": {}
},
{
"event_id": 6,
"event_type": "stateExitedEventDetails",
"event_name": "GetCredentials",
"timestamp": "2021-06-10 23:25:30.280000+03:00",
"previous_event_id": 5
},
{
"event_id": 7,
"event_type": "stateEnteredEventDetails",
"event_name": "Wait1",
"timestamp": "2021-06-10 23:25:30.289000+03:00",
"previous_event_id": 6,
"input_details": {}
},
{
"event_id": 8,
"event_type": "stateExitedEventDetails",
"event_name": "Wait1",
"timestamp": "2021-06-10 23:25:40.289000+03:00",
"previous_event_id": 7
},
{
"event_id": 9,
"event_type": "stateEnteredEventDetails",
"event_name": "Wait2",
"timestamp": "2021-06-10 23:25:40.296000+03:00",
"previous_event_id": 8,
"input_details": {}
},
{
"event_id": 10,
"event_type": "executionFailedEventDetails",
"timestamp": "2021-06-10 23:25:40.296000+03:00",
"previous_event_id": 0,
"error": {
"type": "Runtime",
"cause": "An error occurred while executing the state 'Wait2' (entered at the event id #9). The SecondsPath parameter does not reference an input value: $.request_payload.sec"
}
}
],
"input": {
"callback_url": "https://rock.site/09876ercftvghnj3iy4738c-3crv/",
"transaction_id": "01FG3YHN4FCJ4EYW6326ZAQW6Y",
"response_collection_id": "01FG3YHR1TYXTAAZZHMTX50HQV",
"request_collection_id": "01FG3YHQW2TY3A2GVKX5SXAB4D"
},
"output": {
"response_payload": {
"api_key": "",
"domain": "organization-a1b2c3d4e5f6",
"subdomain": "organization-a1b2c3d4e5f6.staircaseapi.com",
"organization_id": "4321-4321-4321-432"
}
}
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string (uuid)` path | `7c668252-d2ba-job-id-896d-1f73236287d9` | Execution ID |
| `product_name` required | `string` query | `environment-creator` | This parameter is required to be `environment-creator`. Anything else would cause a failure |
| `detailed` | `string` query | `false` | Returns detailed execution history including execution data if set to `true`. Default `false`. |
| `next_token` | `string` query | `oei09uo8yr7tvweyuni29eirv9kod` | If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error. |
| `reverse_order` | `string` query | `true` | Returns events in ascending order of their timeStamp if set to `false`. Default is descending `true`. |
| `max_results` | `integer` query | `100` | The maximum number of results that are returned per call. You can use next-token to obtain further pages of results. The default is 50 and the maximum allowed page size is 1000. This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum. |
##### Response `200``application/json`
6 fields
Execution status successfully retrieved
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Execution status`ABORTED``FAILED``RUNNING``SUCCEEDED``TIMED_OUT` |
| `executed_events` | `string[]` | List of executed events |
| `last_event` | `string` | Last executed event |
| `details` | `object[]` | Executed events details |
| `input` | `object` | Short data you used for invoking the flow. |
| `transaction_id`required | `string` | Transaction ID |
| `request_collection_id`required | `string` | Request collection ID |
| `response_collection_id`required | `string` | Response collection ID |
| `callback_url`required | `string (uri)` | Destination URL on which final result of the flow execution was configured to be sent |
| `output` | `object` | Short data of the output. |
| `response_payload`required | `object` | Response payload. |
| `api_key` | `string` | — |
| `domain` | `string` | — |
| `subdomain` | `string` | — |
| `organization_id` | `string` | — |
| `extraction_errors`required | `one of` | Extraction errors. |
##### Response `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Request forbidden -- authorization will not help |
| `url` | `string (url)` | Indicates at which url the error occurs |
##### Response `404``application/json`
1 fields
Partner, flow or execution not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Nothing matches the given URI |
`POST` `/vendors/staircase/flows/env-create/jobs/{job_id}`
#### Terminate Create Environment Flow Execution
`terminateCreateEnvironmentFlowExecution`
Terminate execution of Create Environment Flow
This endpoint allows stopping execution of Create Environment Flow.
##### Response
201400
application/json Copy Execution successfully terminated
```
{
"job_id": "9348765c-2eda-46d6-9214-7119c175dc5f",
"status": "ABORTED",
"stop_date": "2021-06-25 13:15:34.447000+03:00"
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string (uuid)` path | `7c668252-d2ba-job-id-896d-1f73236287d9` | Execution ID |
| `product_name` required | `string` query | `environment-creator` | This parameter is required to be `environment-creator`. Anything else would cause a failure |
##### Response `201``application/json`
3 fields
Execution successfully terminated
| Field | Type | Description |
| --- | --- | --- |
| `job_id` | `string` | Execution job id. |
| `status` | `string` | Status of the execution. |
| `stop_date` | `string` | Stop date. |
##### Response `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Request forbidden -- authorization will not help |
| `url` | `string (url)` | Indicates at which url the error occurs |
##### Response `404``application/json`
1 fields
Partner, flow or execution not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Nothing matches the given URI |
`GET` `/vendors/staircase/flows/env-create/executions`
#### List Create Environment Flow Executions
`listCreateEnvironmentFlowExecutions`
Retrieve flow executions status
This endpoint allows getting status of flow executions.
##### Response
200400
application/json Copy Executions list successfully retrieved
```
{
"executions": [
{
"job_id": "6b54387a-fe7e-4fb0-ad2a-40c70ebd0f1c",
"flow_name": "ocrolus-ide-classify-and-extract",
"status": "SUCCEEDED",
"start_date": "2021-06-25 13:34:56.441000+03:00",
"stop_date": "2021-06-25 13:37:31.348000+03:00"
},
{
"job_id": "a32f4f6b-a906-4b11-9f96-edaf1dcac592",
"flow_name": "ocrolus-ide-classify-and-extract",
"status": "ABORTED",
"start_date": "2021-06-25 13:06:42.681000+03:00",
"stop_date": "2021-06-25 13:15:34.447000+03:00"
},
{
"job_id": "57340187-45f2-41ea-984a-cdc731a2d7f0",
"flow_name": "ocrolus-ide-classify-and-extract",
"status": "FAILED",
"start_date": "2021-06-25 13:02:19.838000+03:00",
"stop_date": "2021-06-25 13:11:07.252000+03:00"
}
],
"next_token": "AAAAKgAAAAIAAAAAAAAAAcsQMPbdXoFFnzT2rEqFsqrT0zHE/qEYZz+7bsEqn/szszKZGF+UqlAFcP48NpKsyXcxMIaopLnNb398gvFSPLP1AeV3K35+eWnxTNf0J8w+v3jiBLuzY/EaIPtvKlsUP7d1ARcA5Z2pppZqUkDNXgOqxMQTZPAbmyBNST+OdPbMylcX275vZ/0X4PyPvxnYgp53L97rJ0JMcQT/2+/Y8NAJQxsUESi00tv9E/glloA4hyvPAuFW6rZL8VY5bU7kh4LiPL9BmOhKaN+0QazQxaJZJmStj6jN2F27v0FpSkyl+ENTy4nZrw40PlRzg6Es8gZjxouPRD9erBiTahioV4lW9jpIu82rXX4N6e6lK5sfN+p68qNorq+F7jp9LokkC3idROMs4iB4OX2rX7YguDIbgg0NZneQndTE+Opph7eXlxMAXMIbxpSgI5TYyCQIP1GjsE66dCPldJBoogFv9IIEnt/38ZLpyOwwQnGVOLw8O/ARwH+Ev52AJIVUGVNqTA=="
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` query | `environment-creator` | This parameter is required to be `environment-creator`. Anything else would cause a failure |
| `next_token` | `string` query | `p9208y937gtyuhoivju38hry0gvy3ruhifnc3kcd` | If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error. |
| `status_filter` | `string` query | `ABORTED` | If specified, only list the executions whose current execution status matches the given filter. |
| `max_results` | `integer` query | `100` | The maximum number of results that are returned per call. You can use next-token to obtain further pages of results. The default is 50 and the maximum allowed page size is 1000. This is only an upper limit. The actual number of results returned per call might be fewer than the specified maximum. |
##### Response `200``application/json`
2 fields
Executions list successfully retrieved
| Field | Type | Description |
| --- | --- | --- |
| `next_token` | `string` | Pagination token to get next results |
| `executions` | `object[]` | List of executions |
| `job_id` | `string` | Execution ID |
| `flow_name` | `string` | Flow name |
| `status` | `string` | Execution status |
| `start_date` | `string` | Execution start date |
| `stop_date` | `string` | Execution stop date |
##### Response `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Request forbidden -- authorization will not help |
| `url` | `string (url)` | Indicates at which url the error occurs |
##### Response `404``application/json`
1 fields
Partner, flow or execution not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Nothing matches the given URI |
### Operations
`POST` `/activate-auth-token`
#### Activate auth token
`activate-auth-token`
Activates the authentication token on the given environment such token is used for performing operations of management in the environment where the environment product is deployed. IMPORTANT right after deploying environment manager this endpoint should be called, the environment token retrieved by the service should be stored as it is a one time only allowed operation
##### Request
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string (uuid)` | API-KEY received via email upon account creationExample `` |
##### Response `200``application/json`
2 fields
Token activated.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Successful token activation message.`Auth Token activated successfully` |
| `token`required | `string` | Authorization TokenExample `` |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
1 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Environment creation failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`POST` `/disable-environment`
#### Disable environment
`disableEnvironment`
Disable environment used to disable and delete all the resources of a staircase environment assigned to the API-KEY provided.
##### Request
application/jsonExample
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subdomain": "environment-manager"
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"subdomain": "mycoolsubdomain"
}
```
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API-KEY for using the endpoint. |
| `Authorization` required | `string` header | `` | Authorization token. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string` | API-KEY assigned to the environment to be disabled |
| `subdomain`required | `string` | Subdomain assigned to the environment to be disabled |
##### Response `202``application/json`
2 fields
Environment disabled.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Disable process status message. |
| `status`required | `string` | Status of the disabling process. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
3 fields
Unauthorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
| `Message` | `string` | Access denied error message. |
##### Response `403``application/json`
3 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
| `Message` | `string` | Access denied error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Environment disable failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`POST` `/documentation-activate-key`
#### Documentation environment key activation
`activateKey`
This service activates your API key and enables you to preview Staircase product APIs.
##### Request
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string` | API-KEY to be activated in the documentation environment.Example `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `200``application/json`
3 fields
Key activated.
| Field | Type | Description |
| --- | --- | --- |
| `fqdn`required | `string` | Fully qualified domain name of the environment where the key was activated. |
| `status`required | `string` | Status of the key activation. |
| `message`required | `string` | Message about the key activation. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Key Activation error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/env-tools/maintenance-access`
#### Maintenance access
Retrieve a set of temporal credential for the environment to perform maintenance or support tasks
##### Response
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service |
| `Authorization` required | `string` header | `` | Authorizartion token |
| `resource_type` | `string` query | `logs` | resource type for which the access will be granted |
| `access_level` | `string` query | `read` | level of access to the resource |
##### Response `200``application/json`
3 fields
Temporal login credentials
| Field | Type | Description |
| --- | --- | --- |
| `username` | `string` | Username allowed for the temporal access. |
| `account_alias` | `string` | Account alias to be used for accessing. |
| `password` | `string` | One time Password. |
##### Response `400``application/json`
2 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL of the documentation |
| `message` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Access Denied
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting proper access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting proper access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Maintenance access failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/environment/{api_key}`
#### Get environment status
`get-environment`
Get environment Fetch environment status.
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `api_key` required | `string` path | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API-KEY |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Environment creation failure.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`200`
`GET` `/list-environments`
#### List active environments
`list-environments`
List environments Fetch list of active environments.
##### Response
400 application/json400 text/html
application/json Copy Bad request.
```
Bad request
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
##### Response `200``application/json`
1 fields
Response body with the list of child environment active.
| Field | Type | Description |
| --- | --- | --- |
| `environments`required | `object[]` | List of active child environments FQDN and service API-KEY |
| `fqdn` | `string` | Domain name of the environment. |
| `service-key` | `string` | API-KEY of the environment. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Environment not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Server error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Other responses
`401`
`GET` `/service-key/{api_key}`
#### Get service API-KEY
`get-service-key`
Get service key Fetch service key value.
##### Response
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | X-API-KEY for using the service. |
| `Authorization` required | `string` header | `` | Authorization token. |
| `api_key` required | `string` path | `` | Environment API-KEY |
##### Response `200``application/json`
1 fields
Response body with the environment status and, environment details
| Field | Type | Description |
| --- | --- | --- |
| `service_key`required | `string` | UUID value of the service key. |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `401``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `403``application/json`
2 fields
Not Authorized
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL for getting access |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Service key error.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
## Errors
`400``401``403``404``422``500`
## More in Distribution
- Previous product: Console
- Next product: Finance
---
# Finance
# Finance
Metering and billing keyed to the same product identifier every endpoint definition carries.
Finance meters each invocation against the product API it called, using the identifier already present in that endpoint's definition. There is no separate billing catalogue to keep in step with the API catalogue, because they are the same identifier.
Price revisions are versioned per API, and vendor cost is reported alongside what was charged.
## How it works
Metered units can be negative. That is what expresses a charge reversed when a call returned nothing usable — a credit rather than a suppressed record, so the ledger still shows the attempt.
Keeping the attempt visible matters for the waterfall: a vendor tried and returning nothing is exactly the event the ordering is tuned on.
## Operations
### Metrics
`POST` `/metrics`
#### Create Finance Metrics
`createFinanceMetric`
Create Finance Metric
This service enables storing finance metrics. The unit value is a required field that can be either positive or negative according to the direction of the transaction.
##### Request
application/json Copy
```
{
"product_api_identifier": "product_api_identifier_2",
"product_price_identifier": "product_price_identifier_2",
"product_identifier": "c5b45e21-6946-4110-bf83-8ca90fac5493",
"transaction_id": "01G0KZARZ46W8KZ81277V5C0HA",
"request_collection_id": "2I8JNKZARZ46W8KZ81277V5CASD",
"response_collection_id": "328JNKZARZ46W8KZ81277V5SKDS",
"company_name": "customer_comp",
"price_unit_type": "transaction",
"price_timing_type": "completion",
"price_amount": 10,
"price_amount_unit_type": "cents"
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "metric created"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
11 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifier`required | `string` | Unique identifier for payable unitExample `product_api_identifier_1` |
| `product_price_identifier`required | `string` | Unique identifier for priceExample `product_price_identifier_1` |
| `transaction_id` | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `01G0KZARZ46W8KZ81277V5C0HA` |
| `request_collection_id` | `string` | Unique identifier for Staircase request collectionExample `2I8JNKZARZ46W8KZ81277V5CASD` |
| `response_collection_id` | `string` | Unique identifier for Staircase response collectionExample `328JNKZARZ46W8KZ81277V5SKDS` |
| `company_name` | `string` | Company nameExample `comp_name` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant`api_call``datapoint``document``environment``hour``image``page``person``person-hour``pm``pm-hour``product``seat``subscription``transaction`Example `product` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `product_identifier`required | `string` | Unique identifier for productExample `c5b45e21-6946-4110-bf83-8ca90fac5493` |
| `price_amount`required | `number` | Value of the unit in selected unit price. This value can be negative or positive.Example `95` |
| `price_amount_unit_type`required | `string` | Unit of the price`cents`Example `cents` |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`POST` `/products/finance-service/custom_endpoint/create-finance-metric`
#### Create Finance Metric
`createFinanceMetric`
Create finance metric
Create finance metric. Results will be saved in the output collection. Remember transaction_id and response_collection_id from the response to get the collection data from Persistence API: Retrieve Collection
Response collection example
```
{
"metadata": {
"version": 2,
"validation": true,
"product_name": "finance-service"
},
"transaction_id": "01GME0M8HH3TXS0STWANH32VRC",
"collection_id": "01GME0M8KYYBNYQSEVB7MXKVXW",
"data": {
"finance_metrics": [
{
"@id": "01GQJPZJAFSMTB9EDYKGQ85VKK",
"@type": "finance_metric",
"has_finance_metrShow the restic_identifier": {
"has_value": "01GQJPZJAFSMTB9EDYKGQ85VKK"
},
"has_collection_id": {
"has_value": ""
},
"has_organization_id": {
"has_value": "john.doe@test.co"
},
"has_produce_identifier": {
"has_value": "customer"
},
"has_product_api_identifier": {
"has_value": "active"
},
"has_transaction_id": {
"has_value": "test-co-1"
}
}
]
}
}
}
```
##### Request
application/json Copy
```
{
"request_data": {
"finance_metrics": [
{
"has_transaction_id": {
"has_value": "test-co-1"
},
"has_collection_id": {
"has_value": "https://test-co-1.com"
},
"has_organization_id": {
"has_value": "john.doe@test.co"
},
"has_produce_identifier": {
"has_value": "customer"
},
"has_product_api_identifier": {
"has_value": "product-api-identifier"
}
}
]
}
}
```
##### Response
201400
application/json Copy Successfully started flow invocation.
```
{
"invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
"invocation_status": "STARTED",
"product_flow_name": "product_flow_name_example",
"transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
"request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
"response_collection_id": "01F6NAQ4894HPMCBGB4P0G78HG",
"options": {
"dry_run": false
},
"tags": [
"manual verification"
],
"widget_url": "https://product-dev-productsbucket-1j472c4onqkxw.s3.amazonaws.com/widgets/063f5f"
}
```
application/json Copy Bad request
```
{
"message": {
"schema_type": [
"Must be one of: create, update."
]
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `callback_url` | `string (uri)` | Callback URL. |
| `request_data`required | `object` | Request JSON body. |
| `finance_metrics` | `object[]` | Finance metric filter |
| `has_transaction_id` | `object` | Transaction ID |
| `has_value` | `string` | Transaction IDExample `01GQJPZG07MMFTF6ZZ3BVK1ZFP` |
| `has_collection_id` | `object` | Collection ID |
| `has_value` | `string` | Collection IDExample `01GQJPZFXPRR8QMR31CG92J27D` |
| `has_organization_id` | `object` | Organization ID |
| `has_value` | `string` | Organization IDExample `test-co-1@gmail.com` |
| `has_produce_identifier` | `object` | Product Identifier |
| `has_value` | `string` | Product IdentifierExample `customer` |
| `has_product_api_identifier` | `object` | Product API Identifier |
| `has_value` | `string` | Product API IdentifierExample `62f5691e-7fd0-4728-ac3c-977dea07f338` |
##### Response `201``application/json`
12 fields
Successfully started flow invocation.
| Field | Type | Description |
| --- | --- | --- |
| `invocation_id`required | `string` | Invocation ID. |
| `invocation_status`required | `string` | The status of the invocation.`STARTED` |
| `transaction_id`required | `string` | Transaction ID. |
| `request_collection_id`required | `string` | Request collection ID. |
| `response_collection_id`required | `string` | Response collection ID. |
| `product_flow_name` | `string` | Product flow name. |
| `metadata` | `object` | The metadata of the invoked product flow. |
| `callback_url` | `string` | Callback URL. |
| `request_data` | `object` | The data for the request collection. |
| `tags` | `string[]` | List of tags. |
| `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. |
| `widget_url` | `string` | Product widget_url listening on the connector widget_url |
##### Response `400``application/json`
1 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message or object with additional properties. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Request forbidden -- authorization will not help |
| `url` | `string (url)` | Indicates at which url the error occurs |
##### Response `404``application/json`
1 fields
Partner, flow or execution not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Nothing matches the given URI |
`POST` `/metrics/query`
#### Create Asynchronous Metric Query
`create_async_query_execution`
Create Asynchronous Query Execution
The service creates asynchronous query execution to retrieves a list of metrics given one or multiple filters. To retrieve all results, send the request with the same query parameters and next_token provided on the previous call until next_token does not appear in the response.
##### Request
application/json Copy Create asynchronous query execution
```
{
"product_api_identifier": "c4c7a50e-ef10-4885-9a9d-2c04d7410084",
"product_price_identifier": "ecb11b04-e99c-4610-8db1-990367c25883",
"transaction_id": "01F2Q6WJXF5DK3ERTZ18JHSNE8",
"start_date": "2022-04-11",
"end_date": "2022-04-15"
}
```
##### Response
201400 application/json400 text/html403
application/json Copy Ok.
```
{
"query_id": "c62a1228-fae7-44c8-aebe-8706ecfb9fc4",
"status": "IN_PROGRESS"
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
11 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifier` | `string` | Unique identifier for payable unitExample `product_api_identifier_1` |
| `product_price_identifier` | `string` | Unique identifier for priceExample `product_price_identifier_1` |
| `transaction_id` | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `01G0KZARZ46W8KZ81277V5C0HA` |
| `request_collection_id` | `string` | Unique identifier for Staircase request collectionExample `2I8JNKZARZ46W8KZ81277V5CASD` |
| `response_collection_id` | `string` | Unique identifier for Staircase response collectionExample `328JNKZARZ46W8KZ81277V5SKDS` |
| `company_name` | `string` | Company nameExample `comp_name` |
| `price_unit_type` | `string` | The unit of the platform where the price evaluation can be determined as relevant`api_call``datapoint``document``environment``hour``image``page``person``person-hour``pm``pm-hour``product``seat``subscription``transaction`Example `product` |
| `price_timing_type` | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `product_identifier` | `string` | Unique identifier for the productExample `3f312801-e3bb-49c2-a59b-8e2c05958c1b` |
| `start_date`required | `string` | If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format.Example `2021-04-13` |
| `end_date`required | `string` | If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format.Example `2021-04-16` |
##### Response `201``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `query_id` | `string` | Unique identifier for running query execution |
| `status` | `string` | Status of the query execution |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`GET` `/metrics/query/{query_id}`
#### Get Asynchronous Query Result
`get_async_query_result`
The service retrieves a list of metrics by given query id. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.
##### Response
200400 application/json400 text/html403404
application/json Copy Ok.
```
{
"query_id": "fd99d4de-1632-487f-8576-2ee064e75b51",
"status": "SUCCEEDED",
"result_csv_file": "https://finance-athena-result-795294970345.s3.amazonaws.com/fd99d4de-1632-487f-8576-2ee064e75b51.csv&Expires=1659342953",
"data": {
"metrics": [
{
"product_api_identifier": "c4c7a50e-ef10-4885-9a9d-2c04d7410084",
"product_price_identifier": "ecb11b04-e99c-4610-8db1-990367c25883",
"transaction_id": "da2dbe64-33c0-4de2-b5a4-745f0b60ee4c",
"host_environment": "documentation.staircaseapi.com",
"date": "2022-08-01 03:32:42.000",
"company_name": "bohr",
"price_unit_type": "subscription",
"price_timing_type": "monthly",
"price_amount": "10000.0",
"price_amount_unit_type": "cents"
},
{
"product_api_identifier": "df7d610c-0e6e-4bbd-86c0-7de39e29dd8a",
"product_price_identifier": "6c58cf4d-0d97-49dd-8d1a-fd44387734e4",
"transaction_id": "aaa55ebb-43e8-4722-96cd-050bf2b5c29c",
"host_environment": "documentation.staircaseapi.com",
"date": "2022-08-01 03:32:20.000",
"company_name": "bohr",
"price_unit_type": "subscription",
"price_timing_type": "monthly",
"price_amount": "50000.0",
"price_amount_unit_type": "cents"
},
{
"product_api_identifier": "6ee48f0c-7bd8-43de-9bf9-afce5e85bd08",
"product_price_identifier": "4159a209-bc65-48eb-8735-7cb3600d7fa0",
"transaction_id": "2c71d744-9589-4812-a373-e4bcec7df5c5",
"host_environment": "documentation.staircaseapi.com",
"date": "2022-08-01 03:28:51.000",
"company_name": "bohr",
"price_unit_type": "subscription",
"price_timing_type": "monthly",
"price_amount": "100000.0",
"price_amount_unit_type": "cents"
}
]
}
}
```
application/json Copy Error Response.
```
{
"response": {
"value": {
"message": "Filters not allowed ",
"allowed filters": [
"product_name",
"status",
"partner_name",
"metric_type",
"operation_status",
"product_name and severity",
"product_name and status",
"operation_stauts and partner_name",
"start_date and end_date can be combined with every filter"
]
}
}
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `query_id` required | `string` path | `1fc23e2-b13e-405a-a3de-a5228950e3b8` | Unique query execution id |
| `x-api-key` required | `string` header | `` | API key |
| `limit` | `integer` query | `150` | The number of results to return in this request. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
##### Response `200``application/json`
3 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the query execution |
| `result_csv_file` | `string` | URL for query result in CSV format |
| `metrics` | `object[]` | Metrics |
| `host_environment` | `string` | Environment host where the product is deployed. |
| `product_api_identifier` | `string` | Unique identifier for payable unit |
| `product_price_identifier` | `string` | Unique identifier for price |
| `transaction_id` | `string` | Transaction ID |
| `request_collection_id` | `string` | Unique identifier for Staircase request collection |
| `response_collection_id` | `string` | Unique identifier for Staircase response collection |
| `company_name` | `string` | Company name |
| `price_unit_type` | `string` | The unit of the platform where the price evaluation can be determined as relevant |
| `price_timing_type` | `string` | Price is included into billing based on this defined schedule. |
| `price_amount` | `string` | Value of the unit in selected unit price. This value can be negative or positive. |
| `price_amount_unit_type` | `string` | Unit of the price |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Aggregated Metric Migrations
`POST` `/migrations`
#### Create Aggregated Finance Metric Migration Configurations
`createFinanceMigrationConfigurations`
Create Finance Migration Configurations
This service creates migration configurations to allow migrating aggregated finance data to another environment. Aggregated finance data is needed for generating finance reports from them.
##### Request
application/json Copy
```
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "migration configuration created"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `migration_configuration_name`required | `string` | Migration configuration nameExample `test-migration` |
| `target_environment_domain`required | `string` | Domain of target environmentExample `documentation.staircaseapi.com` |
| `target_environment_api_key`required | `string` | API key of given target environmentExample `1111111-22222-333333` |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`GET` `/migrations`
#### List Aggregated Finance Metric Migration Configurations
`listFinanceMigrationConfigurations`
List Finance Migration Configurations
This service allows retrieving Finance product migration configuration
##### Response
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"migration_configurations": [
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "template.staircaseapi.com"
}
]
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `migration_configurations` | `object[]` | Configurations |
| `migration_configuration_name` | `string` | Unique configuration nameExample `test_configuration` |
| `target_environment_api_key` | `string` | Target environment API keyExample `111111-222222-333333` |
| `target_environment_domain` | `string` | Target environment domainExample `documentation.staircaseapi.com` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`PUT` `/migrations/{migration_configuration_name}`
#### Update Aggregated Finance Metric Migration Configurations
`updateFinanceMigrationConfigurations`
Update Finance Migration Configurations
This service updates migration configuration.
##### Request
application/json Copy
```
{
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Success response.
```
{
"message": "migration configuration updated"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `target_environment_domain`required | `string` | Domain of target environmentExample `documentation.staircaseapi.com` |
| `target_environment_api_key`required | `string` | API key of given target environmentExample `1111111-22222-333333` |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`GET` `/migrations/{migration_configuration_name}`
#### Get Aggregated Finance Metric Migration Configurations
`getFinanceMigrationConfigurations`
Get Finance Migration Configurations
This service allows retrieving Finance product migration configuration
##### Response
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"migration_configuration_name": "test_name",
"target_environment_api_key": "apikey",
"target_environment_domain": "documentation.staircaseapi.com"
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/json`
3 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `migration_configuration_name` | `string` | Unique configuration nameExample `test_configuration` |
| `target_environment_api_key` | `string` | Target environment API keyExample `111111-222222-333333` |
| `target_environment_domain` | `string` | Target environment domainExample `documentation.staircaseapi.com` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`DELETE` `/migrations/{migration_configuration_name}`
#### Delete Aggregated Finance Metric Migration Configurations
`deleteFinanceConfigurations`
Delete Finance Configurations
This service allows deleting Finance product configuration
##### Response
200400 error response400 text/html403404
application/json Copy Ok.
```
{
"message": "migration configuration deleted"
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `migration_configuration_name` required | `string` path | `test_configuration_name` | Unique configuration name |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unique configuration nameExample `test_configuration` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
### Reports
`POST` `/reports/finance`
#### Create Finance Metric Reports
`createFinanceMetricReport`
Create Finance Metric Report
This service allows the creation of financial reports for given dates. Request body allows filtering reports by some fields. This service starts asynchronous report execution and returns a unique report ID for checking report execution status and getting report results if report execution is finished.
##### Request
application/json Copy
```
{
"product_api_identifiers": [
"id_1",
"id_2"
],
"product_price_identifiers": [
"product_price_identifier_1",
"product_price_identifier_2"
],
"start_date": "2021-04-13",
"end_date": "2021-05-13"
}
```
##### Response
202400401403404405
application/json Copy Report execution started
```
{
"report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifiers` | `array` | List of API ID |
| `product_price_identifiers` | `array` | List of product price identifier |
| `price_amount_unit_type` | `string` | Price unit`cents`Example `cents` |
| `start_date`required | `string` | Start date in ISO8601 formatExample `2021-04-13` |
| `end_date`required | `string` | End date in ISO8601 formatExample `2021-05-13` |
##### Response `202``application/json`
1 fields
Report execution started
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`POST` `/reports/finance/aggregated`
#### Create Aggregated Finance Metric Reports
`createAggregatedFinanceMetricReport`
Create Aggregated Finance Metric Report
This service allows the creation of financial reports from aggregated metric data for given dates. In order to get a finance report for multiple environments, please have a look at the migrations(/migrations) service for migrating aggregated finance metrics. Request body allows filtering reports by some fields. This service starts asynchronous report execution and returns a unique report ID for checking report execution status and getting report results if report execution is finished. There is no retention period for aggregated finance metrics.
##### Request
application/json Copy
```
{
"product_api_identifiers": [
"id_1",
"id_2"
],
"environments": [
"documentation.staircaseapi.com"
],
"product_price_identifiers": [
"product_price_identifier_1",
"product_price_identifier_2"
],
"start_date": "2021-04-13",
"end_date": "2021-05-13"
}
```
##### Response
202400401403404405
application/json Copy Report execution started
```
{
"report_id": "9a6aa8-4f2-400d-9451-e1e127485"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifiers` | `array` | List of API ID |
| `environments` | `array` | List of environment names |
| `product_price_identifiers` | `array` | List of product price identifier |
| `price_amount_unit_type` | `string` | Price unit`cents`Example `cents` |
| `start_date`required | `string` | Start date in ISO8601 formatExample `2021-04-13` |
| `end_date`required | `string` | End date in ISO8601 formatExample `2021-05-13` |
##### Response `202``application/json`
1 fields
Report execution started
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`GET` `/reports/{report_id}`
#### Get Finance Report Result
`getFinanceReportResult`
This service retrieves the status of a Report Execution for a given report_id. Status = IN_PROGRESS, SUCCEEDED, or FAILED. Continue to ping this service until you receive a status = SUCCEEDED or FAILED. Created report results have one month retention period.
##### Response
200400403404405
application/json Copy Report status
```
{
"report_id": "979a6aa8-4f2-400d-9451-80ee1e127485",
"status": "SUCCEEDED",
"created_at": "2022-05-06:11:53:38",
"finished_at": "2022-05-06:11:55:10",
"expired_at": "1654864684",
"report_data": {
"total": 0,
"price_amount_unit_type": "cents",
"environments": []
}
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
application/json Copy Not found.
```
{
"message": "Not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | API key |
| `report_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | Report ID |
##### Response `200``application/json`
6 fields
Report status
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Report ID |
| `status` | `string` | IN_PROGRESS, FAILED, or SUCCEEDED`FAILED``IN_PROGRESS``SUCCEEDED` |
| `report_data` | `object` | Report payload |
| `created_at` | `string` | Create date of report executionExample `2022-05-06:11:53:38` |
| `finished_at` | `string` | Finish date of report executionExample `2022-05-06:11:55:10` |
| `expired_at` | `string` | Expiration timestamp in string formatExample `1654864684` |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
## Errors
`400``401``403``404``405``422``504`
## More in Distribution
- Previous product: Environment
- Next product: Host
---
# Host
# Host
Deploying a third-party vendor's own software to run inside a customer-managed cloud account.
Some vendors sell software rather than an API, and some data cannot leave a customer's account. Host installs the vendor's engine inside the customer's own environment and operates it there, so the integration behaves like every other one while the documents never leave.
Document-extraction engines are the main case. The vendors installed this way appear below.
## How it works
The alternative was routing documents to a vendor's cloud, which is a different data-residency position and a different contract. Installing the engine locally keeps both the integration surface and the residency boundary intact at once.
## Operations
### Hostings
`POST` `/hostings`
#### Create New
`CreateNewHosting`
Create New Hosting endpoint
##### Request
application/jsonapplication/json
application/json Copy
```
{
"ami_id": "Example AMI",
"instance_type": "Example Instance Type"
}
```
application/json Copy
```
{
"ami_id": null,
"instance_type": null
}
```
##### Response
200400403500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"host_name": "test"
}
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`GET` `/hostings/{hosting_name}`
#### Get by name
`GetHosting`
Get Hosting endpoint
##### Response
200400403404500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"host": "example"
}
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a hosting with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `hosting_name` required | `string` path | `Test` | Hosting Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`DELETE` `/hostings/{hosting_name}`
#### Remove by name
`RemoveHosting`
Remove Hosting endpoint
##### Response
200400403404500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"info": "example"
}
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a hosting with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `hosting_name` required | `string` path | `Test` | Hosting Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
### AMI-Storage
`POST` `/share-ami`
#### Share-AMI
`ShareAMI`
Share AMI
Share AMI endpoint
##### Response
200400 application/json400 text/html403500
application/json Copy Ok.
```
{
"code": 200,
"message": "example"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `string` | Payload |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
### Host
`POST` `/ami-infos`
#### Create New AMI info
`CreateNewAMIInfo`
Create New AMI info endpoint
##### Request
application/jsonapplication/json
application/json Copy
```
{
"ami_id": "Example AMI",
"ami_name": "Example Instance Type",
"health_check_url": "Example Health Check Url"
}
```
application/json Copy
```
{
"ami_id": null,
"ami_name": null,
"health_check_url": null
}
```
##### Response
200400 application/json400 text/html403500
application/json Copy Ok.
```
{
"code": 200,
"message": "AMI info created successfully"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`GET` `/ami-infos/{ami_name}`
#### Get AMI Info
`GetAMIInfo`
Get AMI Info endpoint
##### Response
200400 application/json400 text/html403404500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"host": "example"
}
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a ami information with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ami_name` required | `string` path | `Test` | AMI Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`DELETE` `/ami-infos/{ami_name}`
#### Remove AMI Info
`RemoveAMIInfo`
Remove AMI Info endpoint
##### Response
200400 application/json400 text/html403404500
application/json Copy Ok.
```
{
"code": 200,
"message": "Example"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a ami information with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ami_name` required | `string` path | `Test` | AMI Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`PUT` `/ami-infos/{ami_name}`
#### Update New AMI info
`UpdateNewAMIInfo`
Update New AMI info endpoint
##### Request
application/jsonapplication/json
application/json Copy
```
{
"ami_id": "Example AMI",
"health_check_url": "Example Health Check Url"
}
```
application/json Copy
```
{
"ami_id": null,
"health_check_url": null
}
```
##### Response
200400 application/json400 text/html403500
application/json Copy Ok.
```
{
"code": 200,
"message": "AMI info updated successfully"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ami_name` required | `string` path | `Test` | AMI Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
### SoftworksAI
`POST` `/process-batches`
#### Add New Batch for Processing
`process-tobatches`
Add a new batch for processing.
The service process a batch with one or multiple documents in SoftworksAI. Mortgage documents can be classified and extracted by this service.
Documents can be processed according to the priority specified in the request, you can send High, Medium, and Low.
The batch request will be received and will be in progress, the status of the batch can be got by calling the service /batch-info/{name}, which will provide each generated document status, classification, and ID.
##### Request
application/json Copy An example of a payload.
```
{
"Name": "00-batch-from-api-initial-test-healthy-check-001",
"FileList": [
"https://somebucketname.s3.us-east-1.amazonaws.com/MultiDocs_10_pages.pdf?X-Amz-Algorithm=&X-Amz-Credential=%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=&X-Amz-Expires=1800&X-Amz-Signature=&X-Amz-SignedHeaders=host"
],
"Priority": "High",
"transaction_id": "01FMVZRHRT0B5GWJR5DC36AVWE"
}
```
##### Response
201202400 application/json400 text/html401403422
application/json Copy Created.
```
{
"code": 201,
"message": "IN PROGRESS"
}
```
application/json Copy Accepted.
```
{
"code": 202,
"message": "IN PROGRESS"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `Name`required | `string` | Batch identifier.Example `00-batch-from-api-initial-test-healthy-check-001` |
| `FileList`required | `string[]` | List of files to process. |
| `Priority`required | `string` | Batch processing priority.`High``Low``Medium`Example `High` |
| `transaction_id`required | `string` | Transaction idExample `01FMVZRHRT0B5GWJR5DC36AVWE` |
##### Response `201``application/json`
2 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `string` | Description response. |
##### Response `202``application/json`
2 fields
Accepted.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `string` | Description response. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `408``application/json`
1 fields
Request Timeout.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Timeout error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `409``application/json`
1 fields
Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`GET` `/batch-info/{name}`
#### Retrieve Documents Associated with Batch
`batch-info`
Get all docs associated with a batch
This service get all documents processed under a batch name , the current status and document type identified by SoftworksAI.
A document ID is generated under the following scenarios:
- The batch processed has multiple documents with a URL for each.
- One PDF document with multiple pages, each processed page will have its own document ID.
##### Response
200400 application/json400 text/html401403404422
application/json Copy Ok.
```
[
{
"id": 1
},
{
"name": "00-batch-from-api-initial-test-healthy-check-001"
},
{
"stage": "Recognition"
},
{
"status": "processing"
},
{
"assignedTo": "SYSTEM"
},
{
"scannedDate": "3/12/2021 3:14:04 PM"
},
{
"modifiedDate": "3/12/2021 3:14:04 PM"
},
{
"docType": ""
},
{
"tenantName": ""
},
{
"errorMessage": ""
},
{
"FileList": [
"\\\\10.0.0.123\\Workflow\\TrapezeProject\\Pending\\Batches\\00-batch-from-api-initial-test-healthy-check-001\\2.Recognition\\MultiDocs_10_pages_CV20210312151404.pdf"
]
},
{
"Priority": "High"
}
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Not Found
```
{
"code": "404",
"message": "Not Found."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `00-batch-from-api-initial-test-healthy-check-001` | Name of the batch which extracted data it's being requested. |
##### Response `200``application/json`
16 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `inFileName` | `string` | — |
| `inDocId` | `integer` | — |
| `inNumPages` | `integer` | — |
| `numPages` | `integer` | — |
| `id` | `integer` | — |
| `name` | `string` | — |
| `stage` | `string` | — |
| `status` | `string` | — |
| `assignedTo` | `string` | — |
| `scannedDate` | `string` | — |
| `modifiedDate` | `string` | — |
| `docType` | `string` | — |
| `tenantName` | `string` | — |
| `errorMessage` | `string` | — |
| `FileList` | `string[]` | — |
| `Priority` | `string` | — |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `408``application/json`
1 fields
Request Timeout.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Timeout error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `409``application/json`
1 fields
Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`GET` `/batch-status/{name}`
#### Retrieve Batch Status
`batch-status`
Get batch status
This service get all documents processed under a batch name , the current status and document type identified by SoftworksAI.
A document ID is generated under the following scenarios:
- The batch processed has multiple documents with a URL for each.
- One PDF document with multiple pages, each processed page will have its own document ID.
##### Response
200202400 application/json400 text/html401403404422
application/json Copy Ok.
```
[
{
"id": 1
},
{
"name": "00-batch-from-api-initial-test-healthy-check-001"
},
{
"stage": "Recognition"
},
{
"status": "processing"
},
{
"assignedTo": "SYSTEM"
},
{
"scannedDate": "3/12/2021 3:14:04 PM"
},
{
"modifiedDate": "3/12/2021 3:14:04 PM"
},
{
"docType": ""
},
{
"tenantName": ""
},
{
"errorMessage": ""
},
{
"FileList": [
"\\\\10.0.0.123\\Workflow\\TrapezeProject\\Pending\\Batches\\00-batch-from-api-initial-test-healthy-check-001\\2.Recognition\\MultiDocs_10_pages_CV20210312151404.pdf"
]
},
{
"Priority": "High"
}
]
```
application/json Copy Ok.
```
[
{
"id": 1
},
{
"name": "00-batch-from-api-initial-test-healthy-check-001"
},
{
"stage": "Recognition"
},
{
"status": "processing"
},
{
"assignedTo": "SYSTEM"
},
{
"scannedDate": "3/12/2021 3:14:04 PM"
},
{
"modifiedDate": "3/12/2021 3:14:04 PM"
},
{
"docType": ""
},
{
"tenantName": ""
},
{
"errorMessage": ""
},
{
"FileList": [
"\\\\10.0.0.123\\Workflow\\TrapezeProject\\Pending\\Batches\\00-batch-from-api-initial-test-healthy-check-001\\2.Recognition\\MultiDocs_10_pages_CV20210312151404.pdf"
]
},
{
"Priority": "High"
}
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Not Found
```
{
"code": "404",
"message": "Not Found."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `00-batch-from-api-initial-test-healthy-check-001` | Name of the batch which extracted data it's being requested. |
##### Response `200``application/json`
12 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `integer` | — |
| `name` | `string` | — |
| `stage` | `string` | — |
| `status` | `string` | — |
| `assignedTo` | `string` | — |
| `scannedDate` | `string` | — |
| `modifiedDate` | `string` | — |
| `docType` | `string` | — |
| `tenantName` | `string` | — |
| `errorMessage` | `string` | — |
| `FileList` | `string[]` | — |
| `Priority` | `string` | — |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `408``application/json`
1 fields
Request Timeout.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Timeout error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `409``application/json`
1 fields
Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Other responses
`202`
`GET` `/extract/batch-name/{name}`
#### Retrieve List of Extracted Fields
`extract-all`
Get list of extracted fields
This service returns all extracted documents for one batch in SoftworksAI. For documents with multiple pages, this service returns all documents extracted as well.
##### Response
200400 application/json400 text/html401403404422
application/json Copy Ok.
```
[
{
"fieldlist": [
{
"position": [
{
"page": 1
},
{
"inputFilePageNumber": 1
},
{
"inputFileID": 10015
},
{
"top": 0
},
{
"bottom": 0
},
{
"left": 0
},
{
"right": 0
}
]
},
{
"name": "DocumentType"
},
{
"data": "W-2"
},
{
"dataOriginal": "W-2"
},
{
"conf": 100
}
]
},
{
"id": 10023
},
{
"docType": "W-2"
},
{
"docConf": 93
}
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Not Found
```
{
"code": "404",
"message": "Not Found."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `00-batch-from-api-initial-test-healthy-check-001` | Name of the batch which extracted data it's being requested. |
##### Response `200``application/json`
4 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `fieldList` | `object[]` | — |
| `position` | `object[]` | — |
| `page` | `integer` | — |
| `inputFilePageNumber` | `integer` | — |
| `inputFileID` | `integer` | — |
| `top` | `integer` | — |
| `bottom` | `integer` | — |
| `left` | `integer` | — |
| `right` | `integer` | — |
| `name` | `string` | — |
| `data` | `string` | — |
| `dataOriginal` | `string` | — |
| `conf` | `integer` | — |
| `id` | `integer` | — |
| `docType` | `string` | — |
| `docConf` | `integer` | — |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `408``application/json`
1 fields
Request Timeout.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Timeout error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `409``application/json`
1 fields
Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`PUT` `/{name}/pages`
#### Update And Approve Pages
`updateAndApprovePages`
The service updates And approves pages
##### Request
application/json Copy An example of a payload.
```
[
{
"id": 124,
"docID": 31,
"pageNumber": 1,
"docType": "Form 1003 Uniform Residential Loan Application",
"docConf": 94,
"confThresh": 90,
"split": true,
"outputDocId": 1,
"inputFilePageNumber": 2
}
]
```
##### Response
200400 application/json400 text/html401403422
application/json Copy Ok.
```
{
"code": 200,
"message": "Configuration updated successfully"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `00-batch-from-api-initial-test-healthy-check-001` | Name of the batch which extracted data it's being requested. |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `string` | Status message. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Not Found. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`GET` `/{name}/pages`
#### Get Pages
`getPages`
The service gets pages for the batch
##### Response
200400 application/json400 text/html401403422
application/json Copy Ok.
```
[
{
"id": 167,
"docID": 6,
"pageNumber": 1,
"docType": "Miscellaneous",
"docConf": 52,
"confThresh": 75,
"split": true,
"outputDocId": 0,
"inputFilePageNumber": 1,
"filePath": ""
}
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `00-batch-from-api-initial-test-healthy-check-001` | Name of the batch which extracted data it's being requested. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Not Found. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Other responses
`200`
`GET` `/document_types`
#### Get Document Types
`getDocumentTypes`
The service gets document types
##### Response
200400 application/json400 text/html401403422
application/json Copy Ok.
```
[
"W2"
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Not Found. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Other responses
`200`
`GET` `/document_types/{document_type}/fields`
#### Get Fields
`getFields`
The service gets fields
##### Response
200400 application/json400 text/html401403422
application/json Copy Ok.
```
[
{
"fieldList": [
{
"position": {
"page": 1,
"inputFilePageNumber": 1,
"inputFileID": 2,
"top": 0,
"bottom": 0,
"left": 0,
"right": 0
},
"name": "DocumentType",
"data": "Form 1008 Uniform Underwriting and Transmittal Summary",
"dataOriginal": "Form 1008 Uniform Underwriting and Transmittal Summary",
"conf": 103
}
],
"id": 21,
"docType": "Form 1004C Manufactured Home Appraisal",
"docConf": 89
}
]
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
text/html Copy Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Unprocessable Entity
```
{
"code": "422",
"message": "Unprocessable Entity."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `document_type` required | `string` path | `W2` | Document Type |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Not Found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Not Found. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Other responses
`200`
### Images
`GET` `/images`
#### Get Supported Images
`GetSupportedImages`
Get Supported Images endpoint
##### Response
200400403500
application/json Copy Ok.
```
{
"code": 200,
"message": [
{
"image_name": "host-example",
"suggested_instance_type": "t2.xlarge",
"rules": {
"auto_shutdown": true,
"manual_start": true,
"manual_shutdown": true,
"rdp_access": true,
"auto_start": false
}
}
]
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `array` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
### Actions
`POST` `/hostings/{hosting_name}/start`
#### Hosting Start
`StartHosting`
Start Hosting endpoint
##### Response
200400403404500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"info": "example"
}
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a hosting with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `hosting_name` required | `string` path | `Test` | Hosting Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`POST` `/hostings/{hosting_name}/stop`
#### Hosting Stop
`StopHosting`
Stop Hosting endpoint
##### Response
200400403404500
application/json Copy Ok.
```
{
"code": 200,
"message": {
"info": "example"
}
}
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Error
```
{
"message": "Unable to find a hosting with given parameters."
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `hosting_name` required | `string` path | `Test` | Hosting Name |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `integer` | Status Code. |
| `message` | `object` | Payload |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `404``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
`GET` `/hostings/{hosting_name}/rdp_access`
#### Get RDP Access
`GetRDPAccess`
Get RDP Access endpoint
##### Response
200400403500
application/json Copy Ok.
```
[
"Example"
]
```
application/json Copy Bad request
```
{
"message": "Bad Request"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `hosting_name` required | `string` path | `Test` | Hosting Name |
##### Response `400``application/json`
2 fields
Bad request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
##### Other responses
`200`
### Operations
`GET` `/get-base-url`
#### Get Base URL
`get-base-url-ephesoft`
Provides a base URL to interact with the current installation of Ephesoft web service.
##### Response
200403
application/json Copy Ok.
```
{
"base_url": "http://host-Publi-XXXXXXXXXXXX-1838739269.us-east-1.elb.amazonaws.com:8300"
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `base_url` | `string` | Base URL that can be hit in order to interact with Ephesoft AI’s API. |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error`required | `string` | Error message. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `500``application/json`
1 fields
Batch job creation failure.
| Field | Type | Description |
| --- | --- | --- |
| `error`required | `string` | Error message. |
##### Other responses
`401`
`GET` `/get-license-requirement`
#### Get information to request new license
`get-license-requirement`
Ephesoft partner requires a file and Installation details to request a license from the support portal. This service gets the details needed to request a new license and returns a presigned URL with the document to download.
License portal to get a license from Ephesoft:
##### Response
200400
application/json Copy Ok.
```
{
"total_cores": 2,
"product_version": "2020.1",
"server_os_details": "Microsoft® Windows",
"mac_address": "00:AA:BB:CC:DD",
"database_detail": "DB",
"system_memory": "1GB",
"detail_properties_file": "http://host-Publi-XXXXXXXXXXXX-1838739269.us-east-1.elb.amazo"
}
```
application/json Copy Bad Request
```
{
"code": "400",
"message": "Bad request."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
##### Response `200``application/json`
7 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `total_cores` | `number` | Total cores for your specific environment |
| `product_Error description` | `string` | Version of Ephesoft |
| `server_os_details` | `string` | SO that is currently used for your Ephesoft product |
| `mac_address` | `string` | All mac address that you need to request a license before your complete an installation |
| `database_detail` | `string` | Version of database |
| `system_memory` | `string` | Total memory for server |
| `detail_properties_file` | `string` | URL of request license file |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad request error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
## Providers
- Byte Software
- Ephesoft
- SoftworksAI
## Errors
`400``401``403``404``408``409``422``500``502``503`
## More in Distribution
- Previous product: Finance
- Next product: Marketplace
---
# Marketplace
# Marketplace
The product catalogue and provisioning service: bundles, versioned publication, dependency resolution and single-call rollback.
Publishing makes a bundle installable. The catalogue resolves what a bundle depends on, installs the set, and keeps every published version so a rollback is one call rather than a redeployment.
It also serves the ontology itself. Families, categories, products, APIs and prices are readable and writable through it, so the product tree is queryable rather than only written down.
## How it works
Every publication is proved twice before it ships. A bundle and its dependencies are installed into a long-lived review environment, which proves it can go into an environment that already has state, and into a second environment wiped daily, which proves it can install from nothing. A bundle that cannot do both does not publish.
Those are different failure modes. An installer that assumes prior state breaks on a new customer; an installer that assumes a clean slate breaks on an upgrade. Testing only one of them catches half the class.
## Operations
### Athlete
`POST` `/ontology/athletes`
#### Register Athlete
`register_athlete`
This endpoint registers an `Athlete` entity in the ontology, allowing for future links of such to the `Team` entity.
##### Request
application/json Copy
```
{
"first_name": "Sebastian",
"last_name": "Vettel",
"email": "sebastian.vettel@gmail.com"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name`required | `string` | Athlete's name |
| `last_name`required | `string` | Athlete's surname |
| `email`required | `string` | Email address of the Athlete |
##### Response `201``application/json`
1 fields
Athlete has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `athlete_id` | `string` | Athlete ID referencing the registered Athlete. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/athletes/{athlete_id}`
#### Delete Athlete
`delete_athlete`
This endpoint deletes `Athlete` from the ontology.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/athletes/{athlete_id}`
#### Retrieve Athlete
`retrieve_athlete`
This endpoint retrieves `Athlete` from the ontology. User can additionally request for the team information to which athlete is linked to be returned using the query parameters.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
| `include_team_info` | `boolean` query | `true` | Switch for the team information |
##### Response `200``application/json`
1 fields
Athlete has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `athlete` | `object` | Athlete information |
| `athlete_id`required | `string` | Athlete ID referencing the registered Athlete. |
| `first_name`required | `string` | First name of the Athlete |
| `last_name`required | `string` | Last name of the Athlete |
| `email`required | `string` | Email address of the Athlete |
| `team` | `object` | Team information |
| `team_name`required | `string` | Team name |
| `team_id`required | `string` | Team ID |
| `created_at`required | `string` | Date of the creation |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/athletes/{athlete_id}`
#### Update Athlete
`update_athlete`
This endpoint updates `Athlete` instance in the ontology.
##### Request
application/json Copy
```
{
"first_name": "Sebastian"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name` | `string` | Athlete's first name |
| `last_name` | `string` | Athlete's last name |
| `email` | `string` | Athlete's email address |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Team
`POST` `/ontology/teams`
#### Register Team
`register_team`
This endpoint registers a `Team` entity in the ontology, allowing for future references of such in relation to `Athlete` and `Product` entities.
##### Request
application/json Copy
```
{
"team_name": "Bohr"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `team_name`required | `string` | Team name |
##### Response `201``application/json`
1 fields
Team has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `team_id` | `string` | Team ID referencing the registered Team. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/teams`
#### Retrieve Teams
`retrieve_teams`
This endpoint retrieves all registered Teams in the ontology.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Response `200``application/json`
1 fields
Team has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `teams` | `array` | Array of retrieved Teams |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}`
#### Delete Team
`delete_team`
This endpoint deletes `Team` from the ontology.
#### Warning
If the referenced `Team` has `Athlete` or `Product` linked to it, user should first unlink those and only then proceed with the deletion.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`PATCH` `/ontology/teams/{team_id}`
#### Update Team
`update_team`
This endpoint updates `Team` instance in the ontology.
##### Request
application/json Copy
```
{
"team_name": "Bushnell"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `team_name`required | `string` | Team name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/teams/{team_id}`
#### Retrieve Team
`retrieve_team`
This endpoint retrieves `Team` from the ontology.
#### Query Parameters
User can specify whether the information about the Team's linked products or athletes is needed, which is `false` by default.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `include_athletes_info` | `boolean` query | `true` | Switch for the athlete information |
| `include_products_info` | `boolean` query | `true` | Switch for the product information |
##### Response `200``application/json`
1 fields
Athlete has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `team`required | `object` | Team information |
| `team_name`required | `string` | Team name |
| `team_id`required | `string` | Team ID |
| `created_at`required | `string` | Date of the creation |
| `products` | `array` | Array of products linked to the Team |
| `athletes` | `array` | Array of athletes linked to the Team |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/teams/{team_id}/athletes`
#### Link Athlete to Team
`link_athlete_to_team`
This endpoint links the specified `Athlete` to the provided `Team`. If the `Athlete` is already linked with some `Team`, the request is declined - user should unlink it from that `Team` first.
##### Request
application/json Copy
```
{
"athlete_id": "436bffb6-f398-469b-b619-55f0ecf09b65"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `athlete_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Athlete has been successfully linked to the Team.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}/athletes/{athlete_id}`
#### Unlink Athlete from Team
`unlink_athlete_from_team`
This endpoint unlinks `Athlete` from the provided `Team`. If the provided 'Athlete' is not linked with the given `Team` the request is declined.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`POST` `/ontology/teams/{team_id}/products`
#### Link Product to Team
`link_product_to_team`
This endpoint links the specified `Product` to the provided `Team`. If the `Product` is already linked with some `Team`, the request is declined - user should unlink it from that `Team` first.
##### Request
application/json Copy
```
{
"product_id": "c5b605e0-54bf-45a1-b275-400e3313be9c"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Product has been successfully linked to the Team.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}/products/{product_id}`
#### Unlink Product from Team
`unlink_product_from_team`
This endpoint unlinks `Product` from the provided `Team`. If the provided 'Product' is not linked with the given `Team` the request is declined.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Subscription[warning]
`POST` `/subscriptions`
#### Create Subscription[warning]
`createSubscription`
Create a subscription
Create a subscription for components to keep an environment up to date.
If a component contains dependencies, all dependencies will be added to subscription automatically. After a subscription is created or updated, all new items will be deployed immediately. Response contains the list of subscribed to products including dependencies.
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Show the rest Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404409
application/json Copy Subscription has been created
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested product not found
```
{
"message": "Component was not found"
}
```
application/json Copy Subscription already exist
```
{
"message": "Subscription for domain already exists"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been created
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested product not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Component was not found` |
##### Response `409``application/json`
1 fields
Subscription already exist
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Conflict error message.Example `Subscription for domain already exists` |
`PATCH` `/subscriptions`
#### Extend Subscription[warning]
`updateSubscription`
Extend a subscription.
Extend a subscription for components to keep environment up to date.
This operation will extend existing subscriptions, keeping them together with new ones.
If a component contains dependencies, all dependencies will be added to the subscription automatically. After subscription is created or updated, all new items will be deployed immediately. Response contains the list of new subscribed to products including dependencies.
Show the rest
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.patch(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Subscription has been updated
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subcription not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been updated
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Subcription not found` |
`PUT` `/subscriptions`
#### Modify Subscription[warning]
`modifySubscription`
Modify subscription.
Modifies subscription for components to keep environment up to date.
This operation will overwrite existing subscriptions.
If a component contains dependencies, all dependencies will be added to the subscription automatically. After subscription is created or updated, all new items will be deployed immediately. Response contains the list of new subscribed to products including dependencies.
Show the rest
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.put(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Subscription has been updated
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subcription not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been updated
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Subcription not found` |
`DELETE` `/subscriptions/{domain_name}`
#### Delete Subscription[warning]
`deleteSubscription`
Delete a subscription
Delete subscription from an environment.
If query parameter not specified then a subscription for all components will be deleted.
This will delete deployment history for affected components.
#### Deprecation notice
Marketplace will stop accepting `product_name` and `data_bundle_name` query parameters starting from December 2022. In order to delete subscription from a component, please use `component_name` query parameter instead.
Example:
```
import requests
requests.delete(
f"",
params={"component_name": component_name},
)
```
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subscription not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `component_name` | `string` query | `ComponentName` | The name of the component from Marketplace |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Subscription not found` |
##### Other responses
`204`
`GET` `/subscriptions/{domain_name}/status`
#### Check Status[warning]
`components_delivery_statuses`
Subscription Status
#### Subscription Status
Retrieves a status of delivery for each subscribed component that an environment has subscribed to. Use query parameters to get status by specific component.
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
Show the rest
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
#### Deprecation notice
Starting from December 2022
Marketplace will no longer display status entries inside the `products` and `data` arrays. Status entries will be represented in an array named `components`, and have the following changes:
| Deprecated field | Moved to |
| --- | --- |
| `products[*].product_name` | `components[*].component_name` |
| `products[*].deploy_status` | `components[*].delivery_status` |
| `products[*].using_bundle_id` | `components[*].component_publication_id` |
| `data[*].product_name` | `components[*].component_name` |
| `data[*].deploy_status` | `components[*].delivery_status` |
| `data[*].using_bundle_id` | `components[*].component_publication_id` |
In `products[*].{field name}`, `data[*].{field name}` and `components[*].{field name}` – the `[*]` notation refers to “any item of the array” of `products`, `data` or `components` accordingly.
##### Get changes
Before the new release gets rolled out, users can use `force_compact_status_report` query parameter with the value `true` (case-sensitive) to get responses as documented. When this parameter is provided, Marketplace will respond with new schema changes applied.
Here's the example on how to invoke such request:
```
import json, requests
delivery_statuses = requests.get(
f"",
params={"force_compact_status_report": json.dumps(True)},
)
```
Output example:
```
{
"domain_name": "twenty-uch.staircaseapi.com",
"components": [
{
"delivery_status": "SUCCEEDED",
"component_name": "Connector",
"last_deployment_id": "01GCD2RTN1PT5PE0NHMGV1SQ8R",
"status_updated_date": "2022-09-25T09:29:03.843986+00:00",
"component_publication_id": "01RC91SYEC28WZT714KXQPF0QD"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
##### Response
200400403404
application/json Copy Deployment status per product
```
{
"domain_name": "dev-marketplace.staircaseapi.com",
"components": [
{
"component_name": "Assess-data",
"status_updated_date": "2021-09-20T16:01:51.141673+00:00",
"component_publication_id": "01G18AHNKFAEF3QEKTZJBTDF86",
"delivery_status": "SUCCEEDED",
"last_deployment_id": "01GCD2RTN1PT5PE0NHMGV1SQ8R"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `force_compact_status_report` | `string` query | `true` | Whether or not to use the new version of status representation. Not required for the invocation. |
| `next_token` | `string` query | `eyJhZnRlcl9wcm9kdWN0X3R5cGUiOiAiU0VSVklDRSIsICJhZnRlcl9wcm9kdWN0X25hbWUiOiAiQSIsICJhZnRlcl9kb21haW5fbmFtZSI6ICI5OC51d2lueC5raW5kLmNsb3VkIn0=` | Pagination token. Works only with `force_compact_status_report` applied. |
##### Response `200``application/json`
3 fields
Deployment status per product
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `domain_name` | `string` | Environment domain name.Example `template.staircaseapi.com` |
| `components` | `object[]` | The list of components with delivery statuses. |
| `component_name` | `string` | Component name.Example `Build` |
| `delivery_status` | `string` | Delivery status.`FAILED``INITIATED``IN_QUEUE``SUCCEEDED`Example `SUCCEEDED` |
| `component_publication_id` | `string` | The bundle ID of a component used in the delivery process. Can be null.Example `01G18AHNKFAEF3QEKTZJBTDF86` |
| `status_updated_date` | `string` | Last updated date.Example `2021-09-21T00:27:57.112734+00:00` |
| `last_deployment_id` | `string` | Latest available deployment ID used in delivery. Can be null.Example `01GCD2RTN1PT5PE0NHMGV1SQ8R` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/subscriptions/{domain_name}/deployments`
#### List Deployment History
`getSubscriptionDeployments`
#### List Deployment History
Retrieves deployment history for each component in an environment.
Note: It's recommended to provide specific component name to filter out deployment logs.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400 application/json400 text/html403404
application/json Copy Subscription deployment history by product.
```
{
"domain_name": "template.staircaseapi.com",
"logs": [
{
"deployment_status": "SUCCEEDED",
"component_name": "Build",
"created_at": "2021-05-31T17:45:00.352518+00:00",
"deployment_bundle_id": "620cc74e-4ffe-489c-955e-64e8e1693352"
},
{
"deployment_status": "SUCCEEDED",
"component_name": "Code",
"created_at": "2021-07-02T10:02:18.339430+00:00",
"deployment_bundle_id": "a48e4d44-31d0-4106-8518-1d67e0abb783"
}
],
"page": {
"count": 2,
"next_token": null
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested deployment logs not found
```
{
"message": "Deployment history not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `component_name` | `string` query | `Build` | Component name from Marketplace. If provided, Marketplace will list deployments for this component only. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
3 fields
Subscription deployment history by product.
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain name.Example `template.staircaseapi.com` |
| `logs` | `object[]` | The list of deployment logs. |
| `deployment_bundle_id` | `string` | Deployment bundle ID.Example `ee537ce2-a80e-4ca6-b87b-25056677c10x` |
| `deployment_status` | `string` | Deployment status.Example `SUCCEEDED` |
| `created_at` | `string` | Deployment start invocation date.Example `2021-09-21T00:27:57.112734+00:00` |
| `component_name` | `string` | Component name.Example `Connector` |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested deployment logs not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Deployment history not found` |
`GET` `/subscriptions/environments`
#### List Environments
`getSubscribedEnvironments`
#### List Environments
Retrieves a list of subscribed environments.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Subscribed environments not found
```
{
"message": "Subscribed environments not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
##### Response `200``application/json`
2 fields
Subscribed environments info
| Field | Type | Description |
| --- | --- | --- |
| `environments` | `string[]` | The list of subscribed environments. |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Subscribed environments not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Subscribed environments not found` |
`GET` `/subscriptions/query`
#### List Subscribers of Component
`getSubscribedEnvironmentsPerProduct`
#### List Subscribers of Component
Query Subscribers of Marketplace, subscribed to a particular component.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_name` required | `string` query | `Connector` | Component name from Marketplace |
| `next_token` | `string` query | `eyJhZnRlcl9wcm9kdWN0X3R5cGUiOiAiU0VSVklDRSIsICJhZnRlcl9wcm9kdWN0X25hbWUiOiAiQSIsICJhZnRlcl9kb21haW5fbmFtZSI6ICI5OC51d2lueC5raW5kLmNsb3VkIn0=` | Pagination token. |
| `limit` | `number` query | `50` | Limit the size of output. Must be greater than or equal to 1 and less than or equal to 100. Default values is 50 |
##### Response `200``application/json`
2 fields
Subscribed environments info
| Field | Type | Description |
| --- | --- | --- |
| `next_token` | `string` | Pagination token. |
| `subscribed_domains` | `string[]` | The list of subscribed environments. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`404`
`POST` `/listeners/{listener_kind}/subscriptions`
#### Listen to Deliveries
`create_listener`
#### Listen to Deliveries
`Listen To Deliveries` essentially creates a new listener, then binds it to a subscriber environment. The listener is a configuration of communication strategies.
If the environment, identified by `domain_name` field, does not have a Subscription associated with it, a subscription Listener can't be created for it. The following endpoint is where you can create a subscription: Create Subscription.
Show the rest
#### Listener kinds
##### `realtime`
`realtime` kind of listener solves a strategy whenever delivery of the component occurs.
Delivery of the particular component occurs when:
- Subscription was created for the subscriber environment
- Component has been installed
- Dependency of a direct subscribing component has been installed
#### Strategy kinds
##### `webhook`
`webhook` is the simplest way of notifying a listener. The strategy resolution will result in one-time webhook sent whenever an arbitrary component completes its way to the environment identified by the `domain_name`, it may fail, or it may complete successfully.
Note that, Marketplace sends an HTTP webhook using POST verb without any additional headers, such as Authorization, `x-api-key` etc.
The structure for the webhook payload is defined below:
```
{
"$schema": "",
"type": "object",
"additionalProperties": true,
"examples": [
{
"subscription": {
"elapsed_time": 495.95,
"component_name": "Connector",
"domain_name": "twenty-three.staircaseapi.com",
"status": "SUCCEEDED",
"product_id": "3acd1bb2-ee82-4504-a4fa-9e319811605b"
}
}
],
"properties": {
"subscription": {
"type": "object",
"additionalProperties": true,
"properties": {
"elapsed_time": {
"type": "number",
"description": "Represents how much it took to deliver a component."
},
"component_name": {
"type": "string",
"description": "Component name Marketplace used in delivery."
},
"domain_name": {
"type": "string",
"description": "Represents delivery target."
},
"status": {
"type": "string",
"description": "Represents delivery status.",
"enum": [
"FAILED",
"SUCCEEDED"
]
},
"product_id": {
"type": "string",
"description": "Represents the ID of the product to which the component is linked."
}
}
}
}
}
```
Please note that the schema can be extended to have new fields.
Example of the webhook payload:
```
{
"subscription": {
"elapsed_time": 495.95,
"component_name": "Connector",
"domain_name": "twenty-three.staircaseapi.com",
"status": "SUCCEEDED",
"product_id": "3acd1bb2-ee82-4504-a4fa-9e319811605b"
}
}
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort the request or carry on with creating a listener.
##### Request
application/json Copy
```
{
"domain_name": "example-dot-com.staircaseapi.com",
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"description": "Example dot com environment component updates.",
"strategy": {
"kind": "webhook",
"webhook": {
"url": "https://example.com/partners/staircase-marketplace/webhooks/"
}
}
}
```
##### Response
400403404409422
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Subscriber environment.Example `best.staircaseapi.com` |
| `description` | `string` | Description must fit into 120 characters.Example `Example description.` |
| `strategy` | `object` | Strategy used for notifying the downstream. |
| `kind`required | `string` | Communication kind.`webhook`Example `webhook` |
| `webhook`required | `object` | Webhook object represents receiving url, to which the webhook is sent. |
| `url`required | `string (uri)` | Must be a valid URL with HTTPS scheme.Example `https://google.com/staircase/marketplace/webhooks` |
| `api_key`required | `string` | API key of the subscriber. Is used for validation.Example `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409``422`
`DELETE` `/listeners/{listener_kind}/subscriptions/{domain_name}`
#### Remove Listener
`remove_listener`
#### Remove Listener
Removes listener for a given subscriber identified by `domain_name`. To use `Subscriber validation`, you need to provide an API key in query parameters.
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort the request or carry on with deleting a listener.
##### Response
400403404422
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
| `api_key` required | `string (uuid)` query | `` | API key, which belongs to an environment identified by `domain_name`. |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``422`
`GET` `/listeners/{listener_kind}/subscriptions/{domain_name}`
#### Get Listener
`get_listener`
#### Get Listener
Retrieves the information about the listener, such as strategy and listener kind. If the `api_key` declared in query parameters does not belong to a `domain_name` from path parameters, response parts such as webhook URL will be censored and have a string value of `value__hidden`.
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either obfuscate some parts of the response or return the full information about the listener.
##### Response
200 Basic example of the response200 Example with obfuscation400403404
application/json Copy The listener has been retrieved successfully.
```
{
"listener": {
"strategy": {
"kind": "webhook",
"webhook": {
"url": "https://webhooks.staircaseapi.com/abc-webhooks"
}
},
"description": "Marketplace deliveries monitoring channel."
}
}
```
application/json Copy The listener has been retrieved successfully.
```
{
"listener": {
"strategy": {
"kind": "webhook",
"webhook": {
"url": "value__hidden"
}
},
"description": "Marketplace deliveries monitoring channel."
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
| `api_key` required | `string (uuid)` query | `` | API key, which belongs to an environment identified by `domain_name`. |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
##### Response `200``application/json`
1 fields
The listener has been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `listener`required | `object` | Object representing listener. |
| `domain_name` | `string` | Subscriber environment.Example `best.staircaseapi.com` |
| `description` | `string` | Description must fit into 120 characters.Example `Example description.` |
| `strategy` | `object` | Strategy used for notifying the downstream. |
| `kind`required | `string` | Communication kind.`webhook`Example `webhook` |
| `webhook`required | `object` | Webhook object represents receiving url, to which the webhook is sent. |
| `url`required | `string (uri)` | Must be a valid URL with HTTPS scheme.Example `https://google.com/staircase/marketplace/webhooks` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
### Ontology
`GET` `/ontology/families`
#### List families
`get_families`
#### List Families
Retrieve a list of families registered in catalog.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy List of families.
```
{
"families": [
{
"family_name": "Platform",
"family_id": "da8bc1af-848-454-bfb-14131e81a518",
"description": "Example description",
"created_at": "2022-05-25T15:53:11.237890+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
2 fields
List of families.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `families`required | `object[]` | Array of families. |
| `family_name`required | `object` | Name of the Family.Example `DevOps` |
| `family_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `created_at`required | `string` | Date and time of the latest modification or creation operations. String is in ISO 8601 format.Example `2022-05-25T15:53:11.237890+00:00` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/families`
#### Create family
`create_family`
#### Create Family
Registers a new family in the ontology, returning an identifier in the response payload. Family is at the highest level of ontology. Family identifier can be used to explore categories registered within the family.
#### Naming conventions
The name of the family must fit into one word or an acronym. The name is not a unique identifier of the family. Instead, families are referenced by their unique identifiers, i.e., `family_id`. Family ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"family_name": "Platform"
}
```
##### Response
201400403404409
application/json Copy Family was successfully created.
```
{
"family_id": "df8f01bb-848-4f54-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `family_name`required | `object` | Name of the Family.Example `DevOps` |
##### Response `201``application/json`
1 fields
Family was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `family_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`GET` `/ontology/families/{family_id}/categories`
#### List categories
`get_categories`
#### List Categories
Retrieves a list of categories for a specific Family.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of categories.
```
{
"family_id": "df8f01bb-848-454-bfb-14131e81a518",
"family_name": "Platform",
"categories": [
{
"category_name": "Integrate",
"category_id": "dc8c01bb-848-454-bcb-14131e81c518",
"created_at": "2022-05-20T18:16:16.071810+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `df8f01bb-848-454-bfb-14131e81a518` | Family ID. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `20` | Limit the count of items returned. |
##### Response `200``application/json`
4 fields
Return a list of categories.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `family_id`required | `string` | Unique identified of a family. |
| `family_name`required | `string` | Name of the family under which categories are located. |
| `categories`required | `object[]` | Array of categories |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category. |
| `created_at`required | `string` | Date and time of the latest modification or creation operations. String is in ISO 8601 format.Example `2022-05-25T15:53:11.237890+00:00` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/families/{family_id}/categories`
#### Create category
`create_category`
#### Create Category
Registers a new category under the existing family in the ontology. Category is the second-highest level entity in ontology. Category gets linked to the family it has been created under.
#### Naming conventions
The name of the family must fit into one word or an acronym. The name is not a unique identifier of the category. Instead, categories are referenced by their unique identifiers, i.e., `category_id`. Category ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"category_name": "Integrate"
}
```
##### Response
201400403404409
application/json Copy Category was successfully created.
```
{
"category_id": "dc8c01bb-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `df8f01bb-848-454-bfb-14131e81a518` | Family ID. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `category_name`required | `object` | Name of the Category.Example `Ship` |
##### Response `201``application/json`
1 fields
Category was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`GET` `/ontology/categories/{category_id}/products`
#### List Products
`get_products_in_category`
#### List products
Retrieves a list of products registered in the ontology.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of products.
```
{
"category_id": "dc8c01bb-848-454-bfb-14131e81a518",
"category_name": "Integrate",
"products": [
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Connector",
"created_at": "2022-05-20T18:19:16.071810+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
4 fields
Return a list of products.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category under which product is located. |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/categories/{category_id}/products`
#### Create Product
`create_product`
#### Create Product
Registers a new product under the existing category in the ontology. Product is the third-highest level entity in ontology. Product gets linked to the category it has been created under.
#### Naming conventions
The name of the product must fit into one word or an acronym. The name is not a unique identifier of the product. Instead, families are referenced by their unique identifiers, i.e., `product_id`. Product ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"product_name": "Connector"
}
```
##### Response
201400403404409
application/json Copy Product was successfully created.
```
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `object` | Name of the Product.Example `Build` |
| `category_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Product was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`DELETE` `/ontology/families/{family_id}`
#### Delete Family
`delete_family`
#### Delete Family
Deletes a family from the catalog. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a family if there are categories registered under the family.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Family ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/categories/{category_id}`
#### Delete Category
`delete_category`
#### Delete Category
Deletes category from the ontology. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a category if there are products registered under the category.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/products/{product_id}`
#### Delete Product
`delete_product`
#### Delete Product
Deletes product from the ontology. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a product if there are API entries left registered under the product.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`GET` `/ontology/products/{product_id}/managed_metadata`
#### List Managed Metadata
`get_managed_metadata`
#### List Managed Metadata
Retrieves a list of managed metadata for a specific product.
#### Managed Metadata
Managed metadata is maintained by Marketplace individually for different use-cases. Example of such use-case is code assessment regulator's version hash control.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403
application/json Copy Return a list of managed metadata.
```
{
"product_id": "eea62230-d9fe-4b37-868a-fd7d75d3cb53",
"product_name": "Product",
"metadata_history": [
{
"metadata": {
"version_hash": "version_two"
}
},
{
"metadata": {
"version_hash": "version_one"
}
}
],
"page": {
"next_token": "cGs9UFJPRFVDVCUyM2VlYTYyMjMwLWQ5ZmUtNGIzNy04NjhhLWZkN2Q3NWQzY2I1MyZzaz1NQU5BR0VEX01FVEFEQVRBJTIzUkVWSVNJT04lMjNyZXZpc2lvbiUzQTAxSEpCVFNBNUNDUkFZR0dGMUs1MjhHQTgw",
"count": 2
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
##### Response `200``application/json`
4 fields
Return a list of managed metadata.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name`required | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `metadata_history`required | `object[]` | — |
| `metadata` | `object` | — |
| `version_hash` | `string` | Example `version_two` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400`
`GET` `/ontology/representation`
#### Full Representation Link
`ontology_repr`
#### Represent Full Ontology
Generates URL for the active ontology. Ontology representation describes the whole ontology.
The URL is located under a property named `ontology_url` in the response payload.
#### Example of Ontology Representation
An item within the list of entities of the corresponding entity map provides a link to an upper level entity:
- “category” is aware of the family it's created under. Use `family_id` to navigate back to family.
- “product” is aware of the category it's created under. Use `category_id` to navigate back to category.
- "configuration" is aware of the product it is registered under. Use `product_id` to navigate back to product.
- “API” is aware of the product it's registered under. Use `product_id` to navigate back to product.
- “component” is aware of the product it's created under. Use `product_id` to navigate back to product
- “price” is aware of the API it's created under. Use `product_api_identifier` to navigate back to API.
Example:
Show the rest
```
{
"families": [
{
"family_id": "965b4d6b-4c00-4c50-b321-c991d60dbf30",
"created_at": "2022-07-14T09:45:38.839462+00:00",
"family_name": "DevOps"
},
...
],
"categories": [
{
"category_id": "19a7d3ac-9203-4a5f-bdc9-df7e7951cb56",
"created_at": "2022-07-14T09:45:38.840851+00:00",
"category_name": "Delivery"
},
...
],
"products": [
{
"category_id": "19a7d3ac-9203-4a5f-bdc9-df7e7951cb56",
"created_at": "2022-07-14T09:45:38.841529+00:00",
"product_name": "Marketplace",
"product_id": "01c9df65-4c81-4278-a5b9-501a0e57b4a5"
},
...
],
"api": [
{
"product_api_name": "DescribeDeliveryAttributes",
"product_id": "01c9df65-4c81-4278-a5b9-501a0e57b4a5",
"product_api_identifier": "2b4a383c-604d-46b1-a303-b13e038ca6ed",
"product_api_type": "function",
"product_api_description": "Describe delivery attributes of a certain delivery."
},
...
],
"prices": [
{
"price_invocation_type": "single_partner",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "transaction",
"price_amount": 200,
"product_api_identifier": "2b4a383c-604d-46b1-a303-b13e038ca6ed",
"product_price_identifier": "98190224-9a17-4edc-a285-c1b5ee69a044",
"price_revision_identifier": "revision:01G7Y1K08YB53MAVSF14KZHTC5",
"price_amount_unit_type": "cent"
},
...
],
"components": [
{
"component_name": "Connector",
"product_id": "6ccd1bb2-ee82-4504-b4ca-9e139811506a",
"dependencies": [ "connection-datum", "connection-logger" ]
},
...
]
}
```
#### Notice on Consistency
Note that the ontology representation is regenerated once at a given rate and can be outdated for the sequential changes and link retrieval request.
Marketplace will provide ontology subscription mechanism soon.
##### Response
200400403
application/json Copy The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
```
{
"ontology_url": "https://dev-marketplace-bundles-bucket-us-east-1-293107503335.s3.amazonaws.com/ontology-representation/2025-07-14?AWSAccessKeyId=&Signature=L0ML&x-amz-security-token=&Expires=1657812052"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `200``application/json`
1 fields
The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
| Field | Type | Description |
| --- | --- | --- |
| `ontology_url`required | `string (uri)` | The URL for the ontology.Example `https://dev-marketplace-bundles-bucket-us-east-1-293107503335.s3.amazonaws.com/ontology-representation/2025-07-14?AWSAccessKeyId=&Signature=L0ML&x-amz-security-token=&Expires=1657812052` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400`
`GET` `/ontology/representation/raw`
#### Full Representation
`ontology_repr_json`
#### Represent Full Ontology
Retrieves cached ontology representation. Ontology representation describes the whole ontology.
#### Notice on Consistency
Note that the ontology representation is regenerated once at a given rate and can be outdated for the sequential changes and link retrieval request.
Marketplace will provide ontology subscription mechanism soon.
##### Response
200400403
application/json Copy The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
```
{
"families": [
{
"family_name": "DevOps",
"created_at": "2022-07-13T03:38:06.744123+00:00",
"family_id": "62f5691e-7fd0-4728-ac3c-977dea07f338"
}
],
"categories": [
{
"category_name": "Shipping",
"created_at": "2022-07-13T03:38:06.801765+00:00",
"family_id": "62f5691e-7fd0-4728-ac3c-977dea07f338",
"category_id": "f06e9a78-5eca-441d-a6ae-6ec6a90e703a"
}
],
"products": [
{
"product_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"category_id": "f06e9a78-5eca-441d-a6ae-6ec6a90e703a",
"created_at": "2022-07-13T03:38:06.813104+00:00"
}
],
"configurations": [],
"api": [
{
"product_api_invocation_type": "analytics",
"product_api_description": "Validates a bundle of source code according to the rules configured",
"product_api_type": "function",
"product_api_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"product_api_identifier": "051f6aeb-d1d8-4e0c-80b5-7e59daf68521"
}
],
"prices": [
{
"price_amount_unit_type": "cent",
"price_timing_type": "completion",
"price_calculation_type": "cost_of_goods_sold",
"price_unit_type": "transaction",
"price_amount": 5,
"price_revision_identifier": "revision:01G9FDNFB2ERX0E58WX2R96TGG",
"product_api_identifier": "051f6aeb-d1d8-4e0c-80b5-7e59daf68521",
"product_price_identifier": "930e2bc5-5cb5-4210-b0c3-67e4c76548b7"
}
],
"components": [
{
"component_name": "Assess-security-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess-staircase-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess-swagger-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": []
}
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`200``400`
`GET` `/ontology/products`
#### List Products With Name Filter
`products_by_name`
#### List Products With Name Filter
Retrieves a list of products registered in the ontology, applying the provided filter for product's name. Each Product matching name is returned. Category ID is included in the product ID for the easier navigation upwards.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of products.
```
{
"products": [
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Build",
"created_at": "2022-05-20T18:19:16.071810+00:00",
"category_id": "dc8c01bb-848-454-bfb-14131e81a518"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` query | `Build` | Component name. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `5` | Limit the count of items returned. |
##### Response `200``application/json`
2 fields
Return a list of products.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/{ontology_entity_typename}/{ontology_entity_id}/metadata`
#### Extend Entity Metadata
`update_any_metadata`
Update Metadata
#### Update Metadata
Updates the metadata of the given entity.
Metadata might consist of operational data, which helps to understand how Product owners manage its operations.
- Note: Marketplace appends provided metadata to the existing one, so old fields are kept.
##### Ontology Entities Eligible For Metadata
Path parameter `ontology_entity_typename` can be one of the following:
- `categories`
- `families`
- `products`
##### Request
ConnectionProductMetadataDevOpsFamilyMetadata
application/json Copy
```
{
"metadata": {
"description": "Wrap upstream API operations for multiple partners using \"Connection State Language\".",
"asana_board_id": "23349323054118939",
"asana_board_url": "https://app.asana.com/12/23349323054118939",
"codex": "https://codex.io/managed/Connector",
"documentation": "https://api.staircase.co/docs/Platform/Integrate/Connector",
"homepage": "https://api.staircase.co/docs/Platform/Integrate/Connector#root"
}
}
```
application/json Copy
```
{
"metadata": {
"description": "DevOps – Family of products, which enables you rapid software integration and delivery, providing extremely rich toolset.",
"homepage": "https://api.staircase.co/docs/DevOps#root"
}
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ontology_entity_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Entity ID. Can be an ID for the family, product or category. |
| `ontology_entity_typename` required | `string` path | `families` | Entity typename. Can be `families`, `products` or `categories`. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `metadata`required | `one of` | Information helpful to understand operations of the product. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/{ontology_entity_typename}/{ontology_entity_id}/metadata`
#### Get Entity Metadata
`get_any_metadata`
Get Metadata
#### Get Metadata
Retrieves the metadata of the given entity.
Metadata might consist of operational data, which helps to understand how Product owners manage its operations.
##### Ontology Entities Eligible For Metadata
Path parameter `ontology_entity_typename` can be one of the following:
- `categories`
- `families`
- `products`
##### Response
200400403404
application/json Copy Successfully retrieved Product's Metadata.
```
{
"metadata": {
"asana_board_id": "23349323054118939",
"asana_board_url": "https://app.asana.com/12/23349323054118939",
"codex": "https://codex.io/managed/Connector",
"documentation": "https://api.staircase.co/docs/Platform/Integrate/Connector",
"homepage": "https://api.staircase.co/docs/Platform/Integrate/Connector#root"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ontology_entity_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Entity ID. Can be an ID for the family, product or category. |
| `ontology_entity_typename` required | `string` path | `families` | Entity typename. Can be `families`, `products` or `categories`. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Successfully retrieved Product's Metadata.
| Field | Type | Description |
| --- | --- | --- |
| `metadata`required | `one of` | Information helpful to understand operations of the product. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/families/{family_id}`
#### Update Family[new]
`update_family`
Update Family
#### Update Family
Updates family identified by its identifier.
##### Request
application/json Copy
```
{
"family_name": "Mortgage"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Family ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `family_name`required | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`PATCH` `/ontology/categories/{category_id}`
#### Update Category[new]
`update_category`
Update Category
#### Update Category
Updates category identified by its identifier.
##### Request
application/json Copy
```
{
"category_name": "Tools"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `category_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `family_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/products/{product_id}`
#### Get Product[new]
`get_product`
Get Product
#### Get Product
Retrieves product identified by its identifier.
##### Response
200400403404
application/json Copy Return a product.
```
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Connector",
"created_at": "2022-05-20T18:19:16.071810+00:00"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
4 fields
Return a product.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category under which product is located. |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}`
#### Update Product[new]
`update_product`
Update Product
#### Update Product
Updates product identified by its identifier.
##### Request
application/json Copy
```
{
"product_name": "Connection"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `object` | Name of the Product.Example `Build` |
| `category_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Product
`GET` `/ontology/products/{product_id}/api`
#### Get Product API With Prices[updated]
`join_product_api_with_latest_price`
Get Product API With Prices
#### Get Product API With Prices
Retrieves all registered API entries for a given product. The items in the resulting list are extended with the latest price revision.
If the API is not registered with price revision under it, there will be no price information in the item.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Successfully retrieved API and price revisions.
```
{
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
},
"product_id": "da8bc1af-848-454-bfb-14131e81a518",
"product_name": "Build",
"api": [
{
"api": {
"product_api_name": "CreateArtifactForPackage",
"product_api_description": "Creates an artifact for a given package.",
"product_api_type": "function",
"product_api_identifier": "da8bc1af-848-454-bfb-14131e81a518",
"invocation_type": "analytics"
},
"price": {
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "environment",
"product_price_identifier": "da8bc1af-848-454-bfb-14131e81a518",
"price_revision_identifier": "revision:01G6N30DHYMPRKETP1ACEEXAMP"
}
}
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `5` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 15. If `include_prices` is `false` the limit can have a maximum value of 100. |
| `include_prices` | `string` query | `true` | Flag determines if the output should contain prices along with API entries. true by default |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
4 fields
Successfully retrieved API and price revisions.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `product_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name` | `object` | Name of the Product.Example `Build` |
| `api` | `object[]` | — |
| `api` | `object` | — |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price` | `object` | — |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/api`
#### Register an API
`register_an_api`
#### Register an API
Registers an API for a given product. API is registered under the product. Product is referenced by its ID. APIs can serve as a basis for business value delivery or supervise the latter.
API can be referenced by Product ID and API ID pair. Product ID must be the Product ID under which the API has registered.
#### API type definition
`product_api_type` generalizes the purpose of the API. An API can have three purposes and these are allowed values:
Show the rest
- `configuration` – APIs that control the behaviors of the other APIs.
- `function` – APIs that perform functions.
- `platform `– Platform APIs are those which provide the foundation blocks required by other APIs.
#### API invocation type definition
Staircase evaluates the type of API being invoked in order to determine price. For example, an `aggregated_partner` call will cost more than a `single_partner` call because more partners are being invoked. Usually only mortgage products have `single_partner` and `aggregated_partner` API calls.
- `aggregated_partner` – Staircase APIs call multiple partner’s APIs by creating a partner invocation waterfall.
- `analytics` – Staircase sends the product results in raw report format to the customer.
- `environment` – Staircase APIs call in an environment.
- `notification` – Staircase sends a notification to the customer that the product has completed and results are ready to be viewed.
- `operation` – Staircase has basic 'function' APIs that preform specific operations, like calling product configuration.
- `proxy` – Staircase APIs are proxies of other Staircase products, usually Staircase Platform products. API calls are internal.
- `single_partner` – Staircase APIs only call one partner’s APIs when performing product functions such as data extraction or employment verification.
##### Request
application/json Copy
```
{
"product_api_name": "retrieveImageForGivenRevision",
"product_api_type": "function",
"product_api_description": "Retrieve an image for a given revision number.",
"product_api_invocation_type": "single_partner"
}
```
##### Response
201400403404
application/json Copy Action were associated with the Product successfully. List of URIs follows.
```
{
"product_api_identifier": "dc8a01fa-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
##### Response `201``application/json`
1 fields
Action were associated with the Product successfully. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}/api/{api_id}`
#### Update an API[new]
`update_an_api`
Update an API
#### Update an API
Updates chosen attributes of an API. The update request must introduce with at least one modification.
##### Request
application/json Copy
```
{
"product_api_name": "retrieveImageRevision",
"product_api_type": "platform"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`DELETE` `/ontology/products/{product_id}/api/{api_id}`
#### Delete an API
`deregister_an_api`
Delete API
#### Delete API
Deletes an API for a given product. API can be deleted only if there is no price associated to it.
Once deleted API is never shown in product's API list.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/prices/{price_id}`
#### Delete Price
`delete_price`
#### Delete Price
Permanently deletes a price. It cannot be undone. Also, immediately clears revision history.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `price_id` required | `string (uuid)` path | `bb8b01bb-848-454-bfb-14131e81a518` | Price ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/prices/{price_id}`
#### Get The Latest Price Revision
`get_latest_price`
#### Get The Latest Price Revision
Retrieves the details of the latest revision for the Price.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `price_id` required | `string (uuid)` path | `bb8b01bb-848-454-bfb-14131e81a518` | Price ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
7 fields
Price was successfully deleted.
| Field | Type | Description |
| --- | --- | --- |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/api/{api_id}`
#### Retrieve an API
`retrieve_an_api`
#### Retrieve API
Retrieves an API for a given product.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
API was successfully retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `api` | `object` | API information retrieved. |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PUT` `/ontology/products/{product_id}/api/{api_id}/prices`
#### Create New Price Revision
`create_price_revision`
#### Create New Price Revision
When you create a new price revision it automatically becomes the latest revision.
#### Pricing Description Style and Content
Descriptions should address the "what" of the product – what function is the product performing for the customer? It should begin with a verb that describes what function the API performs. For example: "Verify using multiple partners (waterfall)"
Show the rest The first letter in the price description is uppercase. The remaining words in the pricing description are lowercase unless the word is an acronym like API, or a proper noun like Staircase. Do not put a period or any other punctuation at the end of the pricing description (the descriptions themselves are not sentences and therefore don’t need it).
The `price_unit_type` will be shown as follows to the right of the actual cost, along with the word "per". Do not add `price_unit_type` to the description, for example "price for monthly subscription" is not a preferred description because it lists redundant information rather than tell the customers what functions they’re paying for.
If the `price_unit_type` = `transaction`, Site product will add "per transaction" to the right of the actual cost displayed. Examples:
- "$1.40 per transaction".
If the `price_unit_type` = `subscription`, `environment`, `product` or `user`, the Site product will render the description as "{price_amount (in dollars)} per {price_unit_type}, per month". Examples:
- $100 per subscription, per month
- $9.99 per environment, per month
- $5.00 per product, per month
- $3.40 per user, per month
##### Description Conventions
- If `product_api_invocation_type` = `aggregated_partner`, `description` = Invoke Product Using Multiple Partners.
- If `product_api_invocation_type` = `analytics`, `description` = Generate and Store Analytics for Reporting.
- If `product_api_invocation_type` = `environment`, `description` = Unlimited Use of Product APIs in Environment.
- If `product_api_invocation_type` = `notification`, `description` = Notify via Email and SMS.
- If `product_api_invocation_type` = `operation`, `description` = Invoke a Staircase product API.
- If `product_api_invocation_type` = `proxy`, `description` = Invoke a proxy Staircase API.
- If `product_api_invocation_type` = `single_partner`, `description` = Invoke a Product Using One Partner.
- If `price_unit_type` = `subscription`, `description` should include less than 10 words of details on what function is being performed as part of the subscription. You do not need to include the word “subscription” in the description, as this word should be visible next to the actual price.
##### Mortgage "Partner" Products Example
Mortgage products that make partner calls typically have four different types of pricing as listed in the example below.
NOTE: The environment cost that these products incur is included in the transaction cost, so there is no need to add an "environment cost" per product.
Examples:
- Credit - Verify using multiple partners (waterfall).
- Credit - Verify using one partner.
- Credit - Invoke a proxy Staircase API.
- Credit - Notify upon completion via email and SMS.
- Employment - Verify using one partner.
- Employment - Notify upon completion via email and SMS.
- Employment - Invoke a proxy Staircase API.
- Employment - Verify using multiple partners (waterfall).
- Income - Verify using multiple partners (waterfall).
- Income - Verify using one partner.
- Income - Notify upon completion via email and SMS.
- Income - Invoke a proxy Staircase API.
#### Price definition
- `price_amount` (Required|Number) – Value representing the cost. If non-integer, the value must have a fixed precision of two digits after the decimal point. The inclusive minimum value is `0.01` and the inclusive maximum is `999999.99`
- `price_amount_unit_type` (Required|String) – Value representing the unit of cost. Currently, “cent” is the only allowed value.
- `price_calculation_type` (Required|String) – Different machines of calculating Staircase price per transaction.
- `price_unit_type` (Required|String) – The unit of the platform where the price evaluation can be determined as relevant.
- `price_timing_type` (Required|String) – The price is included into the billing based on this defined schedule.
##### Enumeration variants for fields representing types.
###### price_calculation_type
Staircase determines how price per transaction should be calculated based on the average or overall supplier fee, or on the labor costs saved. For pricing related to premium support, Staircase might also consider how large or mature the customer company is.
- `average_supplier` – The cost is based on the average supplier fee.
- `cost_of_goods_sold` – The cost is based on the overall supplier fee.
- `equivalent_labor_cost` – The cost is based on the labor cost the API saves.
- `maturity` – The cost is based on how large and mature the customer is.
###### price_unit_type
Type of unit that defines which value is used as a measuring location for the calculation.
- `environment` – One charge for an environment and all the product APIs it contains. Monthly.
- `product` – A monthly charge per product. Company and Marketplace are likely to have a “Per Product” monthly charge.
- `seat` – One charge per subscriber, for functions like premium support. No limit to the number of transactions a subscriber can run in a given month.
- `subscription` – A monthly charge per product. Company and Marketplace are likely to have a “Per Product” monthly charge.
- `transaction` – One charge per API call (upon completion of transaction).
- `user` – A monthly charge per user. Setup and possibly PreApproval are likely to have a “Per User” monthly charge, where there is no limit to the number of product transactions a user can run in a given month.
- `api_call` – One charge per API call.
- `document` – One charge per document.
- `hour` – One charge per hour.
- `image` – One charge per image.
- `page` – One charge per page.
- `person` – One charge per person.
- `person_hour` – One charge per person hour.
- `pm` – One charge per product manager.
- `pm_hour` – One charge per product manager hour.
- `datapoint` – One charge per data point retrieved from the document.
###### price_timing_type
Depending on the `price_unit_type`, Staircase will charge upon `completion` or on a `monthly` basis.
###### Allowed values are:
- `completion` – Charged upon completion.
- `monthly` – Charged monthly.
###### Price Unit Types Charged Upon Completion.
Per:
- `transaction`
- `api_call`
- `document`
- `hour`
- `image`
- `page`
- `person`
- `person_hour`
- `pm`
- `pm_hour`
- `datapoint`
###### Price Unit Types Charged On a Monthly Basis.
Per:
- `environment`
- `product`
- `seat`
- `subscription`
- `user`
##### Request
application/json Copy
```
{
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "environment"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
##### Response `200``application/json`
2 fields
Action were associated with the Product successfully. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/many_api`
#### Create Many Product Api With Prices
`create_many_api_with_prices`
#### Create Many Product Api With Prices
This endpoint allows you to register multiple API entries with prices for your product in one call.
In a single request, you can define up to 15 API with price definition merged into it. Marketplace will automatically handle creation of the API and Price for you.
If any of the following statements are true, you cannot use this endpoint:
- Provided product has at least one API associated with it.
- There are more than 15 items in a request payload.
You must use the following endpoints Register an API then Create New Price Revision.
##### Request
application/json Copy
```
[
{
"api": {
"product_api_name": "DistributeConfiguration",
"product_api_type": "function",
"product_api_description": "Distribute given configuration across all subscribed receivers."
},
"price": {
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_unit_type": "transaction",
"price_timing_type": "completion"
}
}
]
```
##### Response
200400403404
application/json Copy Prices and API entries were successfully registered. List of URIs follows.
```
[
{
"api": {
"product_api_identifier": "da8bc1af-848-454-bfb-14131e81a518"
},
"price": {
"product_price_identifier": "da8ac1ab-848-454-bfb-14131e81a518",
"price_revision_identifier": "revision:01G6N30DHYMPRKETP1ACEEXAMP"
}
}
]
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
##### Response `200``application/json`
2 fields
Prices and API entries were successfully registered. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `api`required | `object` | API with the identifier. |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price`required | `object` | Price definition. |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/components`
#### Get Product Components
`list_all_product_components`
#### Get Product Components
Retrieves all linked Components for a given Product.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Successfully retrieved Components
```
{
"product_id": "d126f045-4f0d-4129-b1fb-c0e511d878e5",
"product_name": "Test",
"page": {
"next_token": null,
"count": 2
},
"components": [
"Build",
"Deploy"
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
##### Response `200``application/json`
4 fields
Successfully retrieved Components
| Field | Type | Description |
| --- | --- | --- |
| `product_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name` | `object` | Name of the Product.Example `Build` |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `components` | `array` | — |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/components`
#### Link Components to Product
`link_components_to_product`
#### Link Components to Product
Links given Components to the given product. Product is referenced by its ID.
Component Link can be referenced by Product ID and Component Name pair. Product ID should be the one to which the Component was linked.
#### Component Name
Component Name should be registered in Marketplace, otherwise the request will not be fulfilled.
#### Components Number Limit
This endpoint accepts at most 15 components
##### Request
application/json Copy
```
{
"component_names": [
"Build"
]
}
```
##### Response
201400403404
application/json Copy Components were linked to the Product successfully.
```
{
"components": [
"Build"
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `component_names`required | `array` | Array of Component Names to be linked to the product |
##### Response `201``application/json`
1 fields
Components were linked to the Product successfully.
| Field | Type | Description |
| --- | --- | --- |
| `components` | `array` | Array of linked component names |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/components/{component_name}`
#### Unlink Component from Product
`unlink_components_from_product`
#### Unlink Component from Product
Unlinks given Component from the given product. Product is referenced by its ID. Component should be previously linked to Product ID.
Once unlinked, Component is no more shown in the component list of the product.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
| `component_name` required | `string` path | `Build` | Component Name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Component
`GET` `/{component_registry}`
#### List Components
`listComponents__componentsRepository`
Retrieves a list of components from a particular registry.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200 Service Components List200 Data Configurations List400 application/json400 text/html403
application/json Copy Collection with list of permitted components.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
],
"page": {
"next_token": null,
"count": 2
}
}
```
application/json Copy Collection with list of permitted components.
```
{
"products": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
],
"page": {
"next_token": null,
"count": 2
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `cGs9RU5WSVJPTk1FTlQmc2s9RE9NQUlOJTIzYjAyMTVmNmY=` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `15` | Limits the count of items returned |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Collection with list of permitted components.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
`POST` `/{component_registry}`
#### Register Components
`registerManyComponents__componentsRepository`
Registers many components into the component registry of Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Request
Service ComponentsData Components
application/json Copy
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
##### Response
201 Registered Service Components201 Registered Data Components400 application/json400 text/html403409
application/json Copy Components registry has been updated.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy Components registry has been updated.
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource already exists
```
{
"message": "Registry already contains components."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `409``application/json`
1 fields
Resource already exists
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error messageExample `Registry already contains components.` |
##### Other responses
`201`
`PATCH` `/{component_registry}`
#### Register Component
`registerComponent__componentsRepository`
Registers a component into the component registry of Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Request
Service ComponentData Component
application/json Copy
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
##### Response
201 Registered Service Components201 Registered Data Components400 application/json400 text/html403409
application/json Copy Components registry has been updated.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy Components registry has been updated.
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`201``409`
`GET` `/{component_registry}/{name}`
#### Retrieve Component
`retrieveComponent__componentsRepository`
Retrieves component details such as description, dependencies, created and updated dates.
The response contains the URL to the latest bundle which can be used for deployment.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Component has been retrieved.
```
{
"name": "Marketplace",
"bundle_url": "https://builder-api-dev-codebuilddevbucket-r016i20zh5wi.s3.amazonaws.com/marketplace-main/build/ef5844e1-885d-423b-9ead-97bac72a181c/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1610711553",
"description": "Description",
"dependencies": [
"Build",
"Deploy"
],
"update_at": "2021-01-20T12:54:53.961736+00:00",
"bundle_status": "Valid",
"created_at": "2021-01-05T10:52:31.689233+00:00"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Name of product |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
8 fields
Component has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | ASCII StringExample `Marketplace` |
| `description` | `string` | Component description.Example `DevOps service for building artifacts.` |
| `bundle_url` | `string (uri)` | Temporary URL to access resource. Needs to return 200 status on get request, to be saved.Example `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_meta` | `object` | Bundle meta information. |
| `update_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
| `created_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`PUT` `/{component_registry}/{name}`
#### Update Component
`updateComponent__componentsRepository`
#### Update Component
Uploads new bundle for a component that has already been registered in Marketplace.
##### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Dependency Management
Dependencies are the mechanism of informing the Marketplace if your component depends on another component in the marketplace. It's important to understand that Marketplace Dependency Manager is not a common one. We're not talking about dependency managers, which operate on a library, package, or system level like `pip` or `cargo` do. Marketplace operates on components as dependencies of other components.
##### Types of dependencies
| Type | Description |
| --- | --- |
| Deploy-time | Deploy-time dependency is the one, which your component requires during the deployment. Before delivering a component, Marketplace will attempt to deliver its `deploy-time` dependencies first. |
| Runtime | Runtime dependency is the one, which your component requires during the runtime phase. The delivery of runtime dependencies and components can be optimized by delivering a component and its dependencies in parallel. |
Service components can define `deploy-time` dependencies (defined under `deploy_time_dependencies` field). Defining dependencies (under `dependencies` field) for data configuration components implies that they're deploy-time, hence explicit `deploy-time` (under `deploy_time_dependencies` field) dependencies are prohibited.
###### Dependency resolution
Whenever Marketplace receives a component update, Marketplace performs a shallow dependency resolution to determine the validity of your specification. During this process, Marketplace checks if there are any circular dependencies among deploy-time dependencies of your components, and if there are – you will get an error.
Suppose that the component named “Assess” has the component named “Build” as a deploy-time dependency, and the “Build” attempted to introduce a new deploy-time dependency on the “Assess” component. This will cause an error when maintainers of “Build” try to update their component, introducing a new dependency.
Error payload example:
```
{
"error": {
"message": "Invalid dependency specification. Cycle detected.",
"reason": "Cycle: Assess -> Build -> Assess"
}
}
```
Marketplace still allows circular dependencies for service components, but dependency type cannot be `deploy-time`.
##### Dependency validation
Marketplace will validate the presence and relevance of Assess signature for direct dependencies of your component. If the latest assessment rules have not passed for the component or its dependencies – Marketplace will cancel the publication.
Component's dependencies are allowed to have either latest of second latest `version_hash`.
Error payload example of dependency validation failure:
```
{
"error": {
"message": "Dependencies of Component(`Credit`) are outdated.",
"reason": [
"Component(`Connector`) a dependency of Component(`Credit`) was not signed with the latest or the second latest Assessment version hash.",
"Component(`Language`) a dependency of Component(`Credit`) was not signed with the latest or the second latest Assessment version hash."
],
"_additional_documentation": [
""
]
}
}
```
To summarize, Marketplace has the following restrictions on dependencies:
- Runtime and deploy-time dependencies cannot have intersections. This means that you cannot define a component both as a runtime and deploy-time dependency.
- Component cannot depend on itself.
- Component cannot depend on component which does not have bundles.
- Component cannot depend on component which does not exist.
- Component which is a data configuration cannot have deploy-time dependencies.
- Component and its dependencies cannot have conflicts (cycles).
- Component cannot have dependencies with outdated signature of Assessor's `version_hash`. It must be equal to second latest or latest available to Marketplace.
Use List Component Bundles endpoint to get the second latest and the latest bundle of Assessor. Example:
```
curl -X GET --location "https://.staircaseapi.com/marketplace/products/Assess/bundles?limit=2" \
-H "x-api-key: "
```
The version hash can be located by the following JSONPath: `$.bundles[*].bundle_meta.service-assessor.version_hash`.
#### Product linking
If the instance of Marketplace has products defined in its ontology, components must be linked to those products.
Use Get Product Components endpoint to get components of a product, specified by product's unique ID in `product_id` path parameter. Example:
```
curl -X GET --location "https://.staircaseapi.com/marketplace/ontology/products/{product_id}/components" \
-H "x-api-key: "
```
Use Link Components to Product endpoint to link components to a product, specified by product's unique ID in `product_id` path parameter. Example:
```
curl -X POST --location https://.staircaseapi.com/marketplace/ontology/products//components -H 'x-api-key: ' --data '{"component_names":["{component_name"]}'
```
#### Review Process
The new component configuration will be available in Marketplace only after a Review Process is completed. This process is started automatically. The Review Process status can be monitored using the `review_id` from the response.
#### Delivery
Once the review process is finished successfully, the next phase begins – update propagation.
Update propagation consists of:
- Recursive dependency resolution – every dependency of the component gets introduced to the subscriber.
- Deployment order – determined after resolving dependencies, according to dependency specifications of resolved components.
All the dependencies of the component are also components.
##### Request
application/json Copy
```
{
"bundle_url": "https://example.com/new_bundle.zip",
"description": "New cool product.",
"dependencies": [
"Build",
"Deploy"
]
}
```
##### Response
400 application/json400 text/html403404409422
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
application/json Copy Unprocessable entity
```
{
"message": "Bundle URL is not valid"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_url`required | `string` | The URL of package artifact.Example `https://example.com/new_bundle.zip` |
| `description` | `string` | Short description of product. |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `deploy_time_dependencies` | `string[]` | The list of component's deploy-time dependencies. |
##### Response `202``application/json`
3 fields
New bundle accepted.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Component name.Example `Build` |
| `review_id`required | `string` | Review process ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `bundle_status`required | `string` | Status of the review process.`UPLOADING_IN_PROGRESS`Example `UPLOADING_IN_PROGRESS` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unprocessable entity error messageExample `Bundle URL is not valid` |
##### Other responses
`409`
`POST` `/{component_registry}/{name}/rollback`
#### Rollback Component
`rollbackComponent__componentsRepository`
#### Rollback Component
Reverts the component version to the previous one. This will initiate the update of the component with the previous bundle.
##### Response
400 application/json400 text/html403404409422
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
application/json Copy Unprocessable entity
```
{
"message": "Bundle URL is not valid"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
3 fields
Revert process started.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Component name.Example `Build` |
| `review_id`required | `string` | Review process ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `bundle_status`required | `string` | Status of the review process.`UPLOADING_IN_PROGRESS`Example `UPLOADING_IN_PROGRESS` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unprocessable entity error messageExample `Bundle URL is not valid` |
##### Other responses
`409`
`DELETE` `/{component_registry}/{name}`
#### Delete Component
`deleteComponent__componentsRepository`
Delete a component from components registry.
Note that, in order to delete a component, you must delete all the bundles associated to it.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Success delete.
```
{
"name": "Build"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Success delete.
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | The name of productExample `Build` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/{component_registry}/{name}/bundles`
#### List Component Bundles
`listComponentBundles__componentsRepository`
Retrieves a list of bundles associated with the product. Each bundle contains a unique ID, URL, metadata, description and dependencies.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400 application/json400 text/html403404
application/json Copy 200 response
```
{
"bundles": [
{
"bundle_status": "Valid",
"bundle_id": "01F2H820J56Y2FWEQCNFTYXC33",
"dependencies": [],
"bundle_url": "https://dev-marketplace-bundles-bucket-us-east-1-764911209783.s3.amazonaws.com/SERVICE/Health/01F2H820J56Y2FWEQCNFTYXC33?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1617654330",
"description": "",
"bundle_meta": {
"service-assessor": {
"id": "devops-code-assessor:0d5b6e9c-e7d8-48f8-970e-a82661a1c8b6",
"issuer": "https://documentation.staircaseapi.com/code-assessor",
"status": "SUCCEEDED",
"timestamp": 1617633647.7666585,
"version": "1.0.0"
},
"service-builder": {
"bundle_type": "SERVICE",
"id": "b22de381-a28d-4b3f-bae4-62b7d53b50a8",
"issuer": "https://documentation.staircaseapi.com/infra-builder",
"status": "SUCCEEDED",
"timestamp": 1617633835.1134853,
"version": "1.1"
},
"service-code": {
"commit_hash": "c47eca3d7005b26be4c3ddd3bf164e35dc5e4afe",
"id": "2d17ef8e-355c-4ffb-b933-532881a16e0b",
"issuer": "https://documentation.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1617633512.3986268,
"version": "1.1"
}
},
"uploaded_at": "2021-04-05T14:47:47.013899+00:00"
}
],
"page": [
{
"count": 1,
"next_token": null
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Name of product |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `bundles` | `object[]` | The list of bundles. |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_url` | `string` | Bundle URL.Example `https://example.com/new_bundle.zip` |
| `bundle_id` | `string` | Bundle ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `description` | `string` | Bundle description.Example `My new bundle.` |
| `bundle_meta` | `object` | Bundle meta information. |
| `uploaded_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/{component_registry}/{name}/bundles/{bundle_id}`
#### Retrieve Component Bundle
`getComponentBundle__componentsRepository`
Retrieves component's bundle information which contains a unique ID, URL, metadata, description and dependencies.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `bundle_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Bundle ID |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
7 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `description` | `string` | Component description.Example `My product description.` |
| `bundle_url` | `string (uri)` | Temporary URL to access resource. Needs to return 200 status on get request, to be saved.Example `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_meta` | `object` | Bundle meta. |
| `bundle_id` | `string` | Bundle ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `uploaded_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`DELETE` `/{component_registry}/{name}/bundles/{bundle_id}`
#### Remove Component Bundle
`removeComponentBundle__componentsRepository`
Removes component bundle from Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Success delete.
```
{
"bundle_id": "01F494GQZQPSEGQ8EWRXYG8SBX"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `bundle_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Bundle ID |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Success delete.
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string` | The bundle IDExample `01F494GQZQPSEGQ8EWRXYG8SBX` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/reviews/{review_id}`
#### Retrieve Review Status
`getReviewStatus`
Get information about the review of the bundle that has been uploaded.
##### Response
200400 application/json400 text/html403404
application/json Copy Success response.
```
{
"status": "SUCCEEDED",
"review_details": {
"deploy_logs": "Component has been deployed successfully."
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `review_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Review ID |
##### Response `200``application/json`
2 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `status`required | `string` | Review status.`ABORTED``FAILED``RUNNING``SUCCEEDED``TIMED_OUT`Example `SUCCEEDED` |
| `review_details` | `object` | Review details. |
| `deploy_logs` | `string` | Deploy logs from 'Review environment'. |
| `marketplace_logs` | `object` | Marketplace logs. |
| `comply_logs` | `object` | Compliance logs. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
### Configuration
`POST` `/ontology/products/{product_id}/configurations`
#### Create Product Configuration
`create_configuration`
This endpoint creates Product Configuration linked to different Companies referenced to via respective `company_id` values.
#### Properties
User is expected to set arbitrary description for the configuration to facilitate clarity. `configured_product_id` is a Product that is being configured in the Configuration. Product has to be registered in Marketplace ontology.
Show the rest `configuration_product_api_id` allows to specify the API of the Product the configuration belongs to, enabling higher granularity of the configurations, distinguishing between sub-parts of the same Product.
`company_ids` is a collection of `company_id` values that current configuration is assumed to be associated with. `company_id` references Staircase Company registered in Company product.
#### External Marketplace Product Reference
User can reference products registered on external Marketplace instances by providing the environment information in `configured_product_id` property, as described in the request body schema below. For example, assume you have a product registered on some "my-env.staircaseapi.com" environment. To reference it, you can pass the below to the `configured_product_id` property:
```
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"value": ""
}
```
Note that, once supplied with environment information, `configured_product_api_id` is also verified on the given Marketplace instance.
#### External Company Product Reference
User can reference companies registered on external Company instances by providing the environment information in `company_ids` property, as described in the request body schema below. Follows the same pattern with `configured_product_id` example above.
#### owned_by_company
For Staircase marketplace, the `owned_by_company` property is required to be set to the ID of the company that owns the configuration. ID can be retrieved from the codex post. For external Marketplace instances, the `owned_by_company` property is required but not validated.
##### Request
ExampleExternal MP ProductExternal CompanyConfiguration Product Api
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
},
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
},
"company_ids": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
],
"configuration_product_api_id": "9cab06c2-6bd0-4333-93d6-81987e586a42"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `owned_by_company`required | `string` | Company ID that owns the configuration. |
| `configuration_description`required | `string` | Arbitrary description for the configuration. Limited by 300 symbols. |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `one of` | Allows referencing either local or external MP product |
| `configured_product_api_id` | `string` | Product API that is being configured |
| `company_ids`required | `one of` | Allows referencing either local or external Company product |
##### Response `201``application/json`
1 fields
Product Configuration has been successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `configuration_id` | `string` | Configuration ID that references created Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/configurations`
#### Retrieve Product Configurations
`retrieve_configurations`
Allows to retrieve all Product Configurations created in the environment. `configured_product_id` query value can be specified to filter and retrieve only configurations where specific Product is being configured.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Product Configurations have been retrieved successfully.
```
{
"configurations": [
{
"configuration_description": "first_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKE5HZ",
"01GJXYCAJ6YSJM8MFM3SPGP5HS"
],
"configuration_id": "3d25a250-795b-44db-9cfb-09260fbc9170",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
},
{
"configuration_description": "second_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKEPOS"
],
"configuration_id": "02beaf9c-0e1e-408a-8f71-6bb58f0b29d4",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
}
],
"page": {
"count": 2,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `limit` | `integer` query | `10` | Configurations limit |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `configured_product_id` | `string` query | `da8bc1af-848-454-bfb-14131e81a518` | Product that was configured by Configuration |
##### Response `200``application/json`
2 fields
Product Configurations have been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `configurations` | `array` | Collection of retrieved Configurations |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Delete Product Configuration
`delete_configuration`
This endpoint deletes Product Configuration referenced by its `configuration_id`.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Retrieve Product Configuration
`retrieve_configuration`
This endpoint retrieves Product Configuration referenced by its `configuration_id`.
##### Response
200400403404
application/json Copy Product Configuration has been successfully retrieved.
```
{
"configuration_description": "first_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKE5HZ",
"01GJXYCAJ6YSJM8MFM3SPGP5HS"
],
"configuration_id": "3d25a250-795b-44db-9cfb-09260fbc9170",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Response `200``application/json`
1 fields
Product Configuration has been successfully retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `configuration` | `object` | Contains Configuration information |
| `owned_by_company` | `string` | Company ID that owns the ConfigurationExample `01J063B3X8GEPPGKJV72Q62N26` |
| `configuration_description`required | `string` | Arbitrary configuration description |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `string` | Product configured by Configuration |
| `configured_product_api_id` | `string` | Product API configured by Configuration |
| `company_ids`required | `string[]` | Collection of `company_id` values |
| `configuration_id`required | `string` | Configuration ID used to reference this Configuration |
| `configured_product_host` | `string` | Host environment where the configured Product is registered. |
| `company_host` | `string` | Host environment referenced by the Companies attached to Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Extend Product Configuration
`extend_configuration`
This endpoint enables users to add Company(s) to the given Configuration or to update other properties of it. Configuration is referenced by `configuration_id` in the path. Company(s) to be added must be registered in local Staircase Company product. See the request schema for referencing Companies from the external Staircase Company product.
#### Warning If `company_ids` are to be updated and the given environment does not match already attached companies' environment, the request is rejected.
#### owned_by_company
For Staircase marketplace, the `owned_by_company` property is required to be set to the ID of the company that owns the configuration. ID can be retrieved from the codex post. For external Marketplace instances, the `owned_by_company` property is required but not validated.
##### Request
ExampleExternal CompanyExternal MP Product
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
}
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `owned_by_company` | `string` | Company ID that owns the configuration.Example `01J063B3X8GEPPGKJV72Q62N26` |
| `configured_product_id` | `one of` | Allows referencing either local or external MP product |
| `configured_product_api_id` | `string` | Configured Product API ID. Should be given in pair with `configured_product_id`. |
| `company_ids` | `one of` | Allows referencing either local or external Company product |
| `description` | `string` | Arbitrary configuration description to replace prior one. |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
##### Response `200``application/json`
1 fields
Product Configuration has been successfully extended.
| Field | Type | Description |
| --- | --- | --- |
| `configuration` | `object` | Contains Configuration information |
| `owned_by_company` | `string` | Company ID that owns the ConfigurationExample `01J063B3X8GEPPGKJV72Q62N26` |
| `configuration_description`required | `string` | Arbitrary configuration description |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `string` | Product configured by Configuration |
| `configured_product_api_id` | `string` | Product API configured by Configuration |
| `company_ids`required | `string[]` | Collection of `company_id` values |
| `configuration_id`required | `string` | Configuration ID used to reference this Configuration |
| `configured_product_host` | `string` | Host environment where the configured Product is registered. |
| `company_host` | `string` | Host environment referenced by the Companies attached to Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/configurations`
#### List Configurations by Company
`list_configurations_by_company`
This endpoint retrieves Configurations registered under all Ontology Products filtering by `company_id`. Allows understanding and tracing how and where is Staircase integrating with Partners registered in Company product.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `limit` | `integer` query | `10` | Configurations limit |
| `company_id` | `string` query | `01GJYN5EY5YACHCH071C9KBTR9` | Company ID registered in Company Product |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
##### Response `200``application/json`
2 fields
Configurations have been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `configurations` | `object[]` | Collection of retrieved Configurations |
| `product_id` | `string (uuid)` | Product ID |
| `configuration_id` | `string` | Configuration ID used to reference this Configuration |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/configurations/{configuration_id}/companies`
#### Delete Company(s) from Configuration[new]
`delete_company_from_configuration`
Delete Product Configuration
This endpoint deletes given `company_ids` from the Product Configuration referenced by `configuration_id`. At least 1 Company should be attached to Configuration, so requests to delete all companies are rejected.
##### Request
application/json Copy
```
{
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `company_ids`required | `string[]` | Collection of `company_id` values |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Marketplace Instance
`PUT` `/settings`
#### Update Settings
`updateConfiguration`
Custom Settings
Configures settings for the instance of Marketplace.
| Configuration attribute | Attribute type | Description | Default |
| --- | --- | --- | --- |
| `review_api_key` | API key | Review API key is used for the review process done as a part of publication acceptance. Review process details are not disclosed. If not present publication functionality is not available. | Nothing |
| `self_cleaning_review_api_key` | API key | Second Review API key is used for the review process done as a part of publication acceptance. Optional. The Marketplace will own this environment and perform environment cleaning daily. Cleaning will delete all the data and components deployed on this environment. This environment should not be used for anything except the review process. | Nothing |
| `site_api_key` | API key | Site API key is used for the bundle distribution into Site product located in different location, where bundle's documentation is presented. If not present distribution is cancelled. | Nothing |
| `env_administrator_domain_name` | Domain name | Environment administrator is used to operate deliveries into subscriber environments. | Local environment |
| `env_administrator_api_key` | API key | Environment administrator is used to operate deliveries into subscriber environments. | Local environment |
| `comply_auth_domain_name` | Domain name | Used for authentication user through `Comply Authentication`. | Nothing |
| `code_assessment_regulator` | Regulator | Used for code assessment regulator. | Nothing |
In order to get your own Marketplace instance running, you will have to provide the following required settings:
Show the rest
- `review_api_key` – this will affect publications and review process.
- `env_administrator_domain_name` - this will affect delivery and settings validation.
- `env_administrator_api_key` - this will affect delivery and settings validation.
It is important to note that Environment administrator is a regulatory authority, which can only be located in one environment.
You can check the status of your settings at Check Status.
#### Regulators
Regulators are products that are used for variety of purposes, including code assessment, compliance, and security. The main use-case for regulators is regulator's version hash validation. Currently, Marketplace is able to integrate with the following regulators:
##### Assess
Assess product is a code assessment tool that is used to assess the quality, best-practise conformance, and security of the code that is being published to Marketplace.
Marketplace will store the history of changes to `version_hash` produced in Assess products' signature. Whenever a component of a product gets published, Marketplace will check the `version_hash` of the component, and compare it to the latest valid `version_hash` stored in Marketplace.
Note: Component's dependencies will also be validated. Dependencies must have the latest and previously latest version hash.
###### Updating `version_hash`
Whenever a component linked to Assess product gets published, Marketplace will look for changes in the `version_hash`. If the `version_hash` has changed, Marketplace will store it as the latest valid `version_hash`.
If the Assess regulator is not defined, Marketplace will not check the `version_hash` of the publishing component.
##### Registering Regulator
- Register a new product in ontology, if not registered already
##### Secondary review.
In order to have a secondary review, you need to provide `self_cleaning_review_api_key`. This key will be used for the review process done as a part of publication acceptance. The Marketplace will own this environment and perform environment cleaning daily. Cleaning will delete all the data and components deployed on this environment. This environment should not be used for anything except the review process. Purpose of this environment is to have a clean environment for the review process to validate that the component can be deployed into the fresh environment.
##### Request
application/json Copy
```
{
"review_api_key": "03660bf2-535a-4639-8df2-24322c1d7233",
"env_administrator_api_key": "38ad8edc-1e77-4d73-aff7-c38adb05d78e",
"env_administrator_domain_name": "template.staircaseapi.com",
"site_api_key": "16a75805-acd5-4dca-9ed9-f267a05b330b"
}
```
##### Response
200400 application/json400 text/html403422
application/json Copy Configuration successfully updated.
```
{
"message": "configuration successfully updated"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `review_api_key` | `string` | API key for Review environment.Example `03660bf2-535a-4639-8df2-24322c1d7233` |
| `self_cleaning_review_api_key` | `string` | API key for secondary review environment. Optional.Example `cf9e3809-0ca5-4f16-90f4-92fe612211e9` |
| `env_administrator_api_key` | `string` | API key for Environment Administrator environment.Example `38ad8edc-1e77-4d73-aff7-c38adb05d78e` |
| `env_administrator_domain_name` | `string` | Domain name of Environment Administrator environment.Example `template.staircaseapi.com` |
| `site_api_key` | `string` | API key for Site environment.Example `16a75805-acd5-4dca-9ed9-f267a05b330b` |
| `comply_auth_domain_name` | `string` | Environment domain name, where the "Comply" product runs.Example `no-tr.auth-gateway.staircaseapi.com` |
| `code_assessment_regulator` | `object` | Code assessment regulator. |
| `regulator_product_identifier`required | `string` | Product identifier of regulator.Example `dbcf20b7-0ea6-4bc5-898c-65f51e2d4686` |
##### Response `200``application/json`
1 fields
Configuration successfully updated.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration updating status.Example `Configuration successfully updated` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`422`
`GET` `/settings/status`
#### Check Status
`checkInstanceStatus`
Retrieves the status of the Marketplace installed on your environment. Endpoint validates settings and returns the statuses.
| Settings status | Marketplace operation | When non-operational |
| --- | --- | --- |
| `site_publication` | Site publication | Bundles are not published into Site, and hence documentation is not updated |
| `component_publication` | Bundle distribution | Marketplace cannot review new component bundles |
| `secondary_review_environment_status` | Bundle distribution | Marketplace cleans secondary review environment daily. During the cleaning, publications are not possible. |
| `code_assessment_regulator` | Code assessment regulator | Marketplace cannot validate component's `version_hash` |
#### FAQ
##### What do I have to do if my `site_publication` is non-operational?
Site publications are not a required part of Marketplace publication channel, so it won't affect bundle publication. However, if you're expecting to see documentation updates, we recommend you to configure `site_api_key` via Update Settings
Show the rest
##### What do I have to do if my `component_publication` is non-operational?
Component publication is at the core of continuous delivery in Marketplace. If non-operational, it does not review component updates, which will block continuous delivery of the component. Note that Marketplace might still be able to deliver previously uploaded component bundles.
##### Response
200400 application/json400 text/html403422
application/json Copy Status information container.
```
{
"status": {
"site_publication": {
"is_operational": true
},
"component_publication": {
"is_operational": true
}
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Response `200``application/json`
1 fields
Status information container.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `object` | Collection of resources and their statuses. |
| `site_publication`required | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `component_publication`required | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `code_assessment_regulator` | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `secondary_review_environment_status` | `string` | Secondary review environment status.`Operational``NotSet``CleaningInProgress``EnvironmentBroken`Example `Operational` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`422`
`GET` `/settings/schema`
#### Retrieve Settings Schema[new]
`retrieveSettingsSchema`
Retrieve Settings Schema
Retrieves the relevant Marketplace Settings schema. Example response schema:
```
{
"$schema": "",
"definitions": {
"ConfigureMarketplaceSchema": {
"type": "object",
"properties": {
"comply_auth_domain_name": {
"title": "comply_auth_domain_name",
"type": "string",
"description": "Environment domain name, where the \"Comply\" product runs.",
"pattern": "(^[a-zA-Z0-9]+([a-zA-Z0-9-]+\\.[a-zA-Z0-9-]+){1,61})*[a-zA-Z0-9]+\\.[a-zA-Z]{2,}$"
},
"env_administrator_api_key": {
"title": "env_administrator_api_key",
"type": "string",
"description"Show the rest;: "API key for Environment Administrator environment.",
"minLength": 1
},
"env_administrator_domain_name": {
"title": "env_administrator_domain_name",
"type": "string",
"description": "Domain name of Environment Administrator environment.",
"pattern": "(^[a-zA-Z0-9]+([a-zA-Z0-9-]+\\.[a-zA-Z0-9-]+){1,61})*[a-zA-Z0-9]+\\.[a-zA-Z]{2,}$"
},
"quicksight_api_key": {
"title": "quicksight_api_key",
"type": "string",
"minLength": 1
},
"review_api_key": {
"title": "review_api_key",
"type": "string",
"description": "API key for Review environment.",
"minLength": 1
},
"site_api_key": {
"title": "site_api_key",
"type": "string",
"description": "API key for Site environment.",
"minLength": 1
}
},
"additionalProperties": false
}
},
"$ref": "#/definitions/ConfigureMarketplaceSchema"
}
```
##### Response
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`200`
## Errors
`400``403``404``409``422`
## More in Distribution
- Previous product: Host
- Next product: Setup
---
# Setup
# Setup
Self-service account and environment creation, between a user interface and the platform's own APIs.
Creating an account and its first environment touches several products in a fixed order — identity, environment provisioning, catalogue installation and key issuance. This product carries that sequence so a front end can present it as one step.
Per-vendor credential onboarding follows the same shape: each vendor integration exposes an endpoint to store a lender's credentials and another to describe the schema those credentials must satisfy, so the form can be rendered from the schema rather than hand-built per vendor.
## Operations
### Setup
`POST` `/setupAccount`
#### Setup Account
`setup-account`
Setup new account.
Create new account and send an email
##### Request
application/json Copy An example of a payload.
```
{
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@company.com",
"company_name": "company",
"company_industry": "Mortgage Broker",
"company_size": "1-50",
"address": "STREET",
"zip_code": "00000",
"state": "CA",
"password": "XXXXX"
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"transaction_id": "aaaa-bbb-xccccc"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
##### Request body`application/json`
10 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name`required | `string` | First nameExample `John` |
| `last_name`required | `string` | Last nameExample `Doe` |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `company_name`required | `string` | Company nameExample `company` |
| `company_industry`required | `string` | Category of companyExample `Mortgage Broker` |
| `company_size`required | `string` | Number employees in the companyExample `1-50` |
| `address`required | `string` | AddressExample `STREET` |
| `zip_code`required | `string` | Zip CodeExample `00000` |
| `state`required | `string` | StateExample `CA` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/refresh_token`
#### Refresh Token
`Refresh-token`
Returns new token when access_token expires
##### Request
application/json Copy An example of a payload.
```
{
"refresh_token": ""
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"id_token": "xxxxxx",
"refresh_token": "",
"token_type": "yyyyyy"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `refresh_token`required | `string` | Token to refreshExample `` |
##### Response `200``application/json`
3 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `id_token` | `string` | The ID token. |
| `refresh_token` | `string` | The refresh token. |
| `token_type` | `string` | The token type. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/sign_in`
#### Sign In
`sign-in`
Sign in.
Sign in the credentials
##### Request
application/json Copy An example of a payload.
```
{
"email": "john.doe@company.com",
"password": "XXXXX"
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"id_token": "xxxxxx",
"refresh_token": "",
"token_type": "yyyyyy"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | Email of accountExample `john.doe@company.com` |
| `password`required | `string` | Password of accountExample `XXXXX` |
##### Response `200``application/json`
3 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `id_token` | `string` | The ID token. |
| `refresh_token` | `string` | The refresh token. |
| `token_type` | `string` | The token type. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/check_email_availability/{email}`
#### Check Email Availability
`check-Email-Availability`
Checks email registered incognito pool
##### Response
200400401403500502
application/json Copy OK.
```
{
"status": "AVAILABLE"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `email` required | `string` path | `john.doe@company.com` | Email of account |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of account |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/retrieve_all_products`
#### Get all products
`get-all-products`
Get all products from marketplace
##### Response
200400401403500502
application/json Copy OK.
```
{
"products": [
{
"name": "Account Management",
"description": "",
"status": "NOT_DEPLOY"
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `products` | `object[]` | List of products |
| `name` | `string` | Product name |
| `description` | `string` | Description of product |
| `status` | `string` | Status of deploy of product (NOT_DEPLOY, IN_QUEUE; FAILED, SUCCESS) |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/admin_retrieve_transaction_status`
#### Get environment creation status
`admin_retrieve_transaction_status`
##### Response
200400401403500502
application/json Copy OK.
```
{
"status": "DEPLOYING_INFRASTRUCTURE_PRODUCTS"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of environment |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/submit_customer_api_key`
#### Send email
`submit-customer-api-key`
Submit API key received by email
##### Request
application/json Copy An example of a payload.
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"body": "Task success sent"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `api_key`required | `string` | API key of environmentExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `body` | `string` | Response of endpoint |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/submit_product_deploy_options`
#### Save product selected
`submit-product-deploy-options`
Save product selected of environment created in the front-end side
##### Request
application/json Copy An example of a payload.
```
{
"products_selected": [
"Code",
"Assess"
]
}
```
##### Response
200400401403500502
application/json Copy OK.
```
{
"body": "Task success sent"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Content-Type` required | `string` header | `application/json` | The content type. |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `products_selected`required | `string[]` | Products selected |
##### Response `200``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `body` | `string` | Response of endpoint |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/user-info`
#### Get information about authenticated user
`user-info`
##### Response
200400401403500502
application/json Copy OK.
```
{
"UserAttributes": {
"sub": "xxxxass-xxx-xxxx-xxxx-xxxxxxxxx",
"email_verified": "true",
"company_name": "Staircase",
"email_confirmed": "False",
"api_key_submitted": "True",
"last_name": "Doe",
"setup_id": "xxxxass-xxx-xxxx-xxxx-xxxxxxxxx",
"api_key": "",
"first_name": "John",
"account_id": "xxxxass-xxx-xxxx-xxxx-xxxxxxxxx",
"email": "john.doe@staircase.co",
"company_status": "SETUP_COMPLETED",
"environment_fqdn": "setup-xxx-xxxxxx.staircaseapi.com"
},
"LosAttributes": [
{
"provider": "Encompass",
"credentials": {
"clientId": "xxxxx",
"instanceId": "xxxxx",
"username": "xxxxx"
},
"isAdmin": true,
"adminEmail": "",
"adminPhone": ""
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
2 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `UserAttributes`required | `object` | Information of user |
| `sub`required | `string` | ID of user incognito |
| `email_verified`required | `string` | Email is verified incognito |
| `company_name`required | `string` | Company name of user |
| `email_confirmed`required | `string` | Email was confirmed incognito |
| `api_key_submitted`required | `string` | If the API key was submitted |
| `last_name`required | `string` | Last name |
| `setup_id`required | `string` | ID the user in step functions |
| `api_key`required | `string` | API key of environment related with the user |
| `first_name`required | `string` | First name |
| `account_id`required | `string` | ID of user in account product |
| `email`required | `string` | Email of user |
| `company_status`required | `string` | Status in the flow of setup |
| `environment_fqdn`required | `string` | Domain of environment related with the user |
| `LosAttributes` | `object[]` | List of LOS Providers |
| `provider`required | `string` | Provider name |
| `isAdmin`required | `boolean` | Status if the user is admin |
| `adminEmail` | `string` | The admin email if the user is not Admin |
| `adminPhone` | `string` | The admin phone if the user is not Admin |
| `credentials`required | `object` | Credentials of LOS Configuration |
| `clientId` | `string` | Client ID of LOS Credentials |
| `instanceId` | `string` | Instance ID of LOS Credentials |
| `username` | `string` | Username of LOS Credentials |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/submit_los_configuration/{provider_name}`
#### Create new LOS configuration
`submit_LOS_configuration`
##### Request
application/json Copy An example of a payload.
```
{
"credentials": {
"clientId": "xxxxx",
"instanceId": "xxxxx",
"username": "xxxxx"
},
"isAdmin": true,
"adminEmail": "",
"adminPhone": ""
}
```
##### Response
201400401403500502
application/json Copy OK.
```
{
"message": "The credential was stored successfully"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `provider_name` required | `string` path | `Encompass` | Provider name (NoProvider, Encompass) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `isAdmin`required | `boolean` | Status if the user is admin |
| `adminEmail` | `string` | The admin email if the user is not Admin |
| `adminPhone` | `string` | The admin phone if the user is not Admin |
| `credentials`required | `object` | Credentials of LOS Configuration |
| `clientId` | `string` | Client ID of LOS Credentials |
| `instanceId` | `string` | Instance ID of LOS Credentials |
| `username` | `string` | Username of LOS Credentials |
##### Response `201``application/json`
1 fields
OK.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | Created description. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/sms-templates/{product}`
#### Create new SMS template by product
`create-sms-templates`
##### Request
application/json Copy An example of a payload.
```
{
"text_body": "xxxxxxxx xxxx xxxxxx"
}
```
##### Response
201400401403500502
application/json Copy Created.
```
{
"text_body": "xxxxxxxx xxxx xxxxxx",
"name": "sms_template"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `product` required | `string` path | `Employment` | Product name (Employment, Income) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `text_body`required | `string` | Content of template |
##### Response `201``application/json`
2 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `text_body`required | `string` | Content of template |
| `name`required | `string` | Template name |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/sms-templates/{product}`
#### Retrieve SMS template by product
`retrieve-sms-templates`
##### Response
200400401403500502
application/json Copy Created.
```
{
"text_body": "xxxxxxxx xxxx xxxxxx",
"name": "sms_template"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `product` required | `string` path | `Employment` | Product name (Employment, Income) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
2 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `text_body`required | `string` | Content of template |
| `name`required | `string` | Template name |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/email-templates/{product}`
#### Create new email template by product
`create-email-templates`
##### Request
application/json Copy An example of a payload.
```
{
"html_part": " \n",
"subject_part": "xxxx xxxxx",
"logo_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABA4AAAQcCAYAAAAVwNnQAAA"
}
```
##### Response
201400401403500502
application/json Copy Created.
```
{
"html_part": " \n",
"subject_part": "xxxx xxxxx",
"product_name": "Income"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `product` required | `string` path | `Employment` | Product name (Employment, Income) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `html_part`required | `string` | Content of template |
| `subject_part`required | `string` | Subject of template |
| `logo_data` | `string` | Logo of template in Base64 encode |
##### Response `201``application/json`
3 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `html_part`required | `string` | Content of template |
| `subject_part`required | `string` | Subject of template |
| `product_name`required | `string` | Product Name |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`GET` `/email-templates/{product}`
#### Retrieve email template by product
`retrieve-email-templates`
##### Response
200400401403500502
application/json Copy Created.
```
{
"template": {
"text_body": "xxxxxxxx xxxx xxxxxx",
"name": "sms_template",
"logo_image": "xxxxxxxxxxxxxxxxx"
}
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `product` required | `string` path | `Employment` | Product name (Employment, Income) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
1 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `template`required | `object` | Information about the template |
| `text_body` | `string` | Content of template |
| `name` | `string` | Template name |
| `logo_image` | `string` | URL of logo |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
`POST` `/vendor/{vendor}/credentials`
#### Create credentials by vendor
`create-vendor-credentials`
##### Request
application/json Copy An example of a payload.
```
{
"username": "xxxxxxxx",
"password": "",
"title_provider_orderings": {
"default_ordering": [
"fidelity",
"first_american",
"stewart"
]
}
}
```
##### Response
200400401403422500502
application/json Copy Setup API Triggered Successfully
```
{
"message": "Credentials are saved"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Request data failed validation
```
{
"message": "Invalid request body",
"error": "[object has missing required properties ([\"client_secret\"])]"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `vendor` required | `string` path | `ernst` | Vendor name (ernst) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `username` | `string` | Username of credential |
| `password` | `string` | Password of credential |
| `title_provider_orderings`required | `object` | An object to set default title fees' provider list for states, counties and cities |
| `default_ordering` | `string[]` | Root default ordering for title fees' provider |
| `states` | `object[]` | States |
| `state_code` | `string` | State code |
| `default_ordering` | `string[]` | Default title provider ordering for the state |
| `counties` | `object[]` | Counties |
| `county_name` | `string` | County name |
| `default_ordering` | `string[]` | Default title provider ordering for the county |
| `cities` | `object[]` | Cities |
##### Response `200``application/json`
1 fields
Setup API Triggered Successfully
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `422``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
| `error` | `string` | Message |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Other responses
`404`
`GET` `/vendor/{vendor}/credentials`
#### Retrieve credentials by vendor
`retrieve-vendor-credentials`
##### Response
200400401403500502
application/json Copy An example of a payload.
```
{
"username": "xxxxxxxx",
"password": "",
"title_provider_orderings": {
"default_ordering": [
"fidelity",
"first_american",
"stewart"
]
}
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
| `vendor` required | `string` path | `ernst` | Vendor name (ernst) |
| `Authorization` required | `string` header | `` | Setup authorization token |
##### Response `200``application/json`
3 fields
Setup API Triggered Successfully
| Field | Type | Description |
| --- | --- | --- |
| `username` | `string` | Username of credential |
| `password` | `string` | Password of credential |
| `title_provider_orderings`required | `object` | An object to set default title fees' provider list for states, counties and cities |
| `default_ordering` | `string[]` | Root default ordering for title fees' provider |
| `states` | `object[]` | States |
| `state_code` | `string` | State code |
| `default_ordering` | `string[]` | Default title provider ordering for the state |
| `counties` | `object[]` | Counties |
| `county_name` | `string` | County name |
| `default_ordering` | `string[]` | Default title provider ordering for the county |
| `cities` | `object[]` | Cities |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Other responses
`404`
`POST` `/send-invitation`
#### Send an invitation to new customers
`send-invitation-customer`
##### Request
application/json Copy An example of a payload.
```
{
"company_id": "xxxxxxxx",
"email": "joedoe@test.co",
"first_name": "Joe",
"last_name": "Doe"
}
```
##### Response
200400401403500502
application/json Copy Created.
```
{
"message": "OK"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Unauthorized validation
```
{
"message": "{'data': ['Unauthorized.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
application/json Copy While acting as a gateway or proxy, received an invalid response from the upstream server.
```
{
"message": "The product has encountered an bad gateway error"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key used to identify the API usage plan |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `company_id`required | `string` | The company identifier |
| `email`required | `string` | Customer email |
| `first_name`required | `string` | Customer name |
| `last_name` | `string` | Last Name of customer |
##### Response `200``application/json`
1 fields
Created.
| Field | Type | Description |
| --- | --- | --- |
| `message`required | `string` | message |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `401``application/json`
1 fields
Unauthorized validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `502``application/json`
1 fields
While acting as a gateway or proxy, received an invalid response from the upstream server.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
## Canonical model
- `address`
- `address`
## Property data it reads
- address
## Errors
`400``401``403``404``422``500``502`
## More in Distribution
- Previous product: Marketplace
---
# Shipping
# Shipping
The pipeline: repository operations, assessment, build, deployment, compliance and the orchestration that runs them in order.
How does code get from a repository to a running service?
Each stage is a product with its own API, and the sequence is a separate product that runs them. Keeping the stages independently callable is what lets one run alone — assessing a repository without deploying it is a normal operation rather than a special mode.
## Products
In the order the value chain runs.
1. Assess has a recorded specification
1. Build has a recorded specification
1. Code has a recorded specification
1. Comply has a recorded specification
1. Deploy has a recorded specification
1. Health has a recorded specification
1. Pipeline has a recorded specification
## How the chain fits together
The assessment stage carries one rule that shapes everything downstream: every endpoint declared in a deployment manifest had to appear in the API definition, checked on every build, blocking the build where it did not. A service's contract surface therefore lives at a canonical path in the repository rather than in a document beside it.
---
# Assess
# Assess
A rules engine over infrastructure definitions, fetched at run time, with a version hash that blocks publication against a stale rule set.
Assess runs before anything is built. The service definition is checked against a rule set covering the deployment manifest, the API definition, and the security, distribution, identity and logging conventions every service is required to follow.
The rules are fetched at run time rather than vendored into each repository, so tightening a rule is one edit at the source and the next build everywhere picks it up.
## How it works
One rule carries the most weight. Named `EndpointDocumentationNotExists`, it asserts that every endpoint declared in the deployment manifest also appears in the API definition — checked on every build, blocking the build where it did not hold.
No endpoint could be released undocumented, so the API definitions stayed at their canonical paths and each service's contract surface is readable off its repository.
Publication is gated on a version hash over the joined rule hashes. Three naming rules are excluded from the join, and their absence in any form makes every generated hash differ — the note on record says the hash is deliberately broken in that case, to stop a broken version publishing.
When a component linked to Assess publishes, the catalogue reads the bundle's hash, compares it against the last one recorded, and updates the hash required for publication when it differs. A build against a stale rule set therefore fails at publication rather than shipping quietly.
## Operations
### Assess
`POST` `/assessments`
#### Create Assessment
`new-assessment`
Assess validates a bundle of source code (Identified by a source_url) according to the rules configured for Assess.
Assess returns an assessment_id in the response body. To retrieve the results of the validation, call Retrieve Assessment Status with the assessment_id.
##### Request
application/json Copy
```
{
"source_url": "https://code-dev-0258.s3.amazonaws.com/code-assessor/1506dbf2/source.zip?AWSAccessKeyId=2323"
}
```
##### Response
application/json Copy 200 response
```
{
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `source_url`required | `string` | URL to project source code. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `assessment_id` | `string` | Assessment id, used for get assessment status |
##### Other responses
`400``401``403``404`
`GET` `/assessments/{assessment_id}`
#### Retrieve Assessment Status
`assessment-status`
Retrieve Assessment Status retrieves the results of the validation performed by Assess for the given assessment_id.
##### Response
200 Succeeded response200 Failed response
application/json Copy 200 response
```
{
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"logs": "[Container]2021/01/29 19:44:20 Waiting for agent ping [Container]",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"issuer": "https://api.staircaseapi.com/code_assessor",
"status": "SUCCEEDED",
"timestamp": 1611949487.728646,
"version": "1.0.0"
},
"service-code": {
"commit_hash": "5a8d1bbd276306e73ad5fcb1c45dfe3bb2e6c5c2",
"id": "1506dbf2-ea7b-4b76-9f51-2ebb0ac49af1",
"issuer": "https://api.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1611948276.2954555,
"version": 1.1
}
},
"source_url": "https://code-assessor-oybto4.s3.amazonaws.com/assessments/devops-code-assessor-a51a-56d91d7ed7df/build.zip?AWSAccessKeyId=2525&Signature=TyI1LC0",
"status": "SUCCEEDED",
"warnings": [
{
"errors": [
{
"message": "Run pipeline was expected",
"path": "jobs.Pipeline.name"
}
],
"file": ".github/workflows/pipeline.yml",
"message": "Your pipeline configuration is not compliant",
"rule_code": "pipeline"
}
]
}
```
application/json Copy 200 response
```
{
"errors": [
{
"errors": [
{
"message": "'ServiceApiKeyID' is a required property",
"path": "resources.Resources.ApiUsagePlanCustom.Properties"
},
{
"message": "'UsagePlanName' is a required property",
"path": "resources.Resources.ApiUsagePlanCustom.Properties"
}
],
"file": "./serverless.yml",
"message": "Your UsagePlan is not compliant",
"rule_code": "usagePlan"
},
{
"errors": [
{
"message": "'LoggingBucket' is a required property",
"path": "resources.Resources"
}
],
"file": "./serverless.yml",
"message": "Your loggingBucket S3 is not compliant",
"rule_code": "loggingBucket"
}
],
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"logs": "[Container]2021/01/29 19:44:20 Waiting for agent ping [Container]",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"issuer": "https://api.staircaseapi.com/code_assessor",
"status": "SUCCEEDED",
"timestamp": 1611949487.728646,
"version": "1.0.0"
},
"service-code": {
"commit_hash": "5a8d1bbd276306e73ad5fcb1c45dfe3bb2e6c5c2",
"id": "1506dbf2-ea7b-4b76-9f51-2ebb0ac49af1",
"issuer": "https://api.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1611948276.2954555,
"version": 1.1
},
"status": "FAILED"
},
"warnings": [
{
"errors": [
{
"message": "Run pipeline was expected",
"path": "jobs.Pipeline.name"
}
],
"file": ".github/workflows/pipeline.yml",
"message": "Your pipeline configuration is not compliant",
"rule_code": "pipeline"
}
]
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `assessment_id` required | `string` path | `devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg` | id of assessment |
##### Response `200``application/json`
6 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `errors` | `object` | Contains errors on failed assessment |
| `errors` | `object[]` | Errors array |
| `message` | `string` | Error message |
| `path` | `string` | Path of the property or location issue in your file |
| `file` | `string` | Assessed file |
| `message` | `string` | Error message |
| `rule_code` | `string` | Rule code |
| `source_url` | `string` | Presigned URL with the assessed bundle and including metadata in the header for Assess and other products. This metadata is in use as a signature of successful assessment. |
| `status` | `string` | Status of assessment`FAILED``FAULT``IN_PROGRESS``NOT_FOUND``STOPPED``SUCCEEDED``TIMED_OUT` |
| `metadata` | `object` | Assessment metadata plus metadata included in the assessment presigned URL coming from other products |
| `logs` | `string` | Contains log on failed assessment |
| `warnings` | `object` | Contains warnings on assessment |
| `errors` | `object[]` | Errors array |
| `message` | `string` | Error message |
| `path` | `string` | Path of the property or location issue in your file |
| `file` | `string` | Assessed file |
| `message` | `string` | Error message |
| `rule_code` | `string` | Rule code |
##### Other responses
`400``401``403``404`
`POST` `/assessments/overview`
#### Create Overview Assessment
`new-overview-assessment`
Create Assessment Overview
Assess Overview validates an input of overview in String format according to the rules configured for Assess.
Assess returns an assessment_id in the response body. To retrieve the results of the validation, call Retrieve Assessment Status with the assessment_id.
##### Request
application/json Copy
```
{
"overview": "Overview html template
",
"dictionary": [
"source_url",
"x-api-key"
]
}
```
##### Response
application/json Copy 200 response
```
{
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `overview` | `string` | Overview in string format |
| `dictionary` | `string[]` | Words to omit in spell check |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `assessment_id` | `string` | Assessment id, used for get assessment status |
##### Other responses
`400``401``403``404`
`POST` `/assessments/swagger`
#### Create Assessment Swagger
`new-assessment-swagger`
Assess Swagger validates an input of swagger in JSON format according to the rules configured for Assess. Assess returns an assessment_id in the response body. To retrieve the results of the validation, call Retrieve Assessment Status with the assessment_id.
##### Request
application/json Copy
```
{
"swagger": {
"info": {
"title": "Assess",
"x-product-category": "Ship",
"x-product-family": "DevOps",
"x-product-name": "Assess"
}
},
"dictionary": [
"source_url",
"x-api-key"
]
}
```
##### Response
application/json Copy 200 response
```
{
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `swagger` | `object` | Swagger in JSON format |
| `dictionary` | `string[]` | Words to omit in spell check |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `assessment_id` | `string` | Assessment id, used for get assessment status |
##### Other responses
`400``401``403``404`
`GET` `/version-hash`
#### Retrieve Version Hash
`get-version-hash`
Retrieve Version Hash retrieves the assessment version hash currently available in an environment.
##### Response
application/json Copy 200 response
```
{
"version_hash": "5a8d1bbd276306e73ad5fcb1c45dfe3bb2e6c5c2"
}
```
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `version_hash`required | `string` | Version hash of the latest commit of the Assess repository |
### Assessment Rules
`GET` `/rules-category`
#### Retrieve List of Assessment Rules
`get-rules`
Retrieve List of Assessment Rules retrieves a list of all assessments rules configured for Assess.
##### Response
application/json Copy 200 response
```
[
{
"code": "usagePlan",
"description": "Usage Plan assessment rules"
},
{
"code": "swagger",
"description": "Swagger assessment rules"
}
]
```
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `code`required | `string` | Code of the rule |
| `description`required | `string` | Description of the rule |
##### Other responses
`400``401``403``404`
`GET` `/rule/{code}`
#### Retrieve Assessment Rule
`get-rule`
Retrieve Assessment Rule retrieves an assessment rule for a given code. A list of code are returned by the service Retrieve List of Assessment Rules.
##### Response
application/json Copy 200 response
```
{
"type": "object",
"description": "Usage Plan assessment rules",
"required": [
"handler"
],
"properties": {
"handler": {
"const": "handler"
}
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `code` required | `string` path | `usagePlan` | Rule code from the service Retrieve the list of all assessment rules |
##### Response `200``application/json`
4 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` | Type of the schema |
| `description` | `string` | Description of the schema |
| `required` | `string[]` | Mandatory schema parameters |
| `properties` | `object` | Schema characteristics |
##### Other responses
`400``401``403``404`
`POST` `/rule`
#### Update Assessment Rule
`post-rule`
Update Assessment Rule updates an assessment rule configured for Assess. Assessment rules are configured in JSON format, as defined in
List of available actions:
- insert_product_names: Add new product names.
- remove_product_names: Delete product names.
- update_server_url_pattern: Set server URL pattern using regular expression.
- insert_schema_rule: Add a new rule in the schema.
- remove_schema_rule: Delete a rule by name.
- remove_schema: Delete a schema.
- replace_all_schemas: Replace all schema action allows changing or add multiple rules at the same time by just replacing the complete schema.
Important considerations:
Show the rest
- This feature only allows updating swaggerProductName, serviceProductName, serverlessProductName and swaggerBase schema rules.
- You can get the rule code by the service Retrieve List of Assessment Rules.
- You can see the complete schema by the service Retrieve Assessment Rule.
##### Request
Insert product namesRemove product namesUpdate server url patternInsert schema ruleRemove schema ruleReplace all schema
application/json Copy
```
{
"rule_name": [
"swaggerProductName",
"serviceProductName",
"serverlessProductName"
],
"action": "_insert_product_names",
"product_names": [
"Account",
"Test"
]
}
```
application/json Copy
```
{
"rule_name": [
"swaggerProductName",
"serviceProductName",
"serverlessProductName"
],
"action": "_remove_product_names",
"product_names": [
"Account",
"Test"
]
}
```
application/json Copy
```
{
"rule_name": [
"swagger"
],
"action": "_update_server_url_pattern",
"server_url_pattern": "^https://documentation.staircaseapi.com/?[-_a-zA-Z0-9/]+$"
}
```
application/json Copy
```
{
"rule_name": [
"swagger"
],
"action": "_insert_schema_rule",
"schema": {
"api": {
"type": "object",
"required": [
"handler"
],
"properties": {
"handler": {
"const": "handler"
}
}
}
}
}
```
application/json Copy
```
{
"rule_name": [
"swagger"
],
"action": "_remove_schema_rule",
"schema_rule_name": "api"
}
```
application/json Copy
```
{
"rule_name": [
"swagger"
],
"action": "_replace_all_schema",
"schema": {
"type": "object",
"required": [
"handler"
],
"properties": {
"handler": {
"const": "handler"
}
}
}
}
```
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `rule_name`required | `string[]` | Schema name |
| `action`required | `string` | Action to execute on the rule |
| `product_names` | `string[]` | Product names to insert or delete |
| `server_url_pattern` | `string` | Regular expression to validate the server URL |
| `schema_rule_name` | `string` | Schema rule name to insert or delete |
| `schema` | `object` | Schema of the rule defined in this format |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | SUCCEEDED |
##### Other responses
`400``401``403``404`
## Errors
`400``401``403``404`
## More in Shipping
- Next product: Build
---
# Build
# Build
One build contract producing five bundle types, so a conversational agent, a front end, a vendor mapping and a service all move through the same pipeline.
Three files describe a unit of work: what it is, what it exposes, and how it deploys. From those, the build produces one of five bundle types — a service, a data bundle, a front end, a front-end configuration, or a chat bundle.
The bundle is the deployable unit everywhere downstream. Deploy takes it, Marketplace publishes it, and Environment installs it.
## How it works
Making a vendor mapping and a React front end the same kind of artifact is what lets one pipeline cover every unit of work. A vendor configuration is not code in the usual sense, but it versions, tests and deploys like everything else, and a separate release path for it would have been a second pipeline to keep correct.
## Operations
### Product
`POST` `/builds`
#### Build Product
`buildProduct`
Build a deployable artifact for a product. The artifact must be provided via a URL. A callback will be sent to the URL specified in `callback_url` property.
#### `Build Hash`
The builder generates a unique hash value for each build. This value is available in build metadata which can be accessed using the product information endpoint. Also, this value passes by a Deployer if the AWS CloudFormation parameter definition exists in product `serverless.yml`. This parameter can be referenced as an environment variable as follows.
Show the rest Product serverless.yml:
```
provider:
environment:
BUILD_HASH:
Ref: BuildHash
...
resources:
Parameters:
BuildHash:
Type: String
Description: This info will be generated by the Builder and passed by Deployer. It contains a product build hash.
Default: "null"
```
#### `architecture`
By default, X86_64 architecture is used to build dependencies. Switch to ARM64 using the 64-bit ARM architecture for the AWS Graviton2 processor. It is possible to use only one architecture per build.
#### `node_version`
You can configure Node version to use to package your dependencies. Please note, that `node_version` = 14 works only with `architecture` = X86_64 and `compute_instance_size` = SMALL. `node_version` 18 and 20 works only with `architecture` = ARM64 and `compute_instance_size` = SMALL.
#### `compute_instance_size`
You can configure how much memory and disk space your build can take up. `compute_instance_size` is dependent on `architecture`. The following table describes mapping of allowed architectures to compute instance sizes.
| Architecture | Compute instance size | Memory | Disk space | vCPUs |
| --- | --- | --- | --- | --- |
| ARM64 | SMALL | 4 GB | 50 GB | 2 |
| ARM64 | LARGE | 16 GB | 50 GB | 8 |
| X86_64 | SMALL | 3 GB | 64 GB | 2 |
##### Request
application/json Copy
```
{
"source_url": "https://code-manager-dev-root.s3.amazonaws.com/service-builder-api/2f867413-2f16-4c73-86ec-3086c0d4a33c/source.zip"
}
```
##### Response
201400
application/json Copy Build created
```
{
"build_id": "13bd5b51-1a41-4510-9baa-d7f7e24c89a3"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Request body`application/json`
8 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `source_url`required | `string (uri)` | Presigned URL to source code. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for build status |
| `serverless_version` | `string` | Serverless version, that is used in build process to update serverless framework version.`2.x``3.x`Example `3.x` |
| `log_level` | `string` | Log level, that is used in build process. Can be used with \"DEBUG\" value for Build product debugging.`DEBUG``INFO`Example `INFO` |
| `architecture` | `string` | Architecture used to build your bundle dependencies.`ARM64``X86_64`Example `X86_64` |
| `node_version` | `string` | Node version used to package your dependencies. 14 version works only with X86_64, small instance.`12``14``18``20`Example `12` |
| `compute_instance_size` | `string` | Compute instance size defines the computational instance used during the build.`LARGE``SMALL`Example `SMALL` |
##### Response `201``application/json`
1 fields
Build created
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build_id which can be used for tracking build status. Usually it is a UUID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
`GET` `/builds/{build_id}`
#### Retrieve Product Build Status
`getBuildStatus`
Retrieve Service Build Status retrieves metadata generated by the build.
- Metadata is available only for builds that succeed (status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was built. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
- Regardless of status response contains build execution logs
##### Response
200400
application/json Copy 200 response
```
{
"build_id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"status": "SUCCEEDED",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:e5dcb19e-b025-4255-a42f-7f501456703c",
"timestamp": 1623399920.05132,
"version": "1.0.0",
"issuer": "https://build.staircaseapi.com/code-assessor",
"status": "SUCCEEDED"
},
"service-code": {
"id": "0da65dfd-9753-4bb4-8853-06e608979e73",
"timestamp": 1623399796.747468,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "c366156be0d8a39ce9a7bf85a5f5d5fc1a59ba4c",
"issuer": "https://build.staircaseapi.com/code"
},
"service-builder": {
"id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"timestamp": 1623400025.2152104,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://build.staircaseapi.com/infra-builder"
}
},
"artifacts_url": "https://builder-api-dev-codebuilddevbucket-kkwqngshvjap.s3.amazonaws.com/build-main/build/7ac245b7-2f93-485-8e8-abfdfd3b0a76/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1623405346",
"logs": [
"[Container] 2021/06/11 08:26:14 Waiting for agent ping\n",
"[Container] 2021/06/11 08:26:17 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 CODEBUILD_SRC_DIR=/codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2021/06/11 08:26:17 No commands found for phase name: post_build\n",
"[Container] 2021/06/11 08:26:17 Processing environment variables\n",
"[Container] 2021/06/11 08:26:17 Moving to directory /codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 Registering with agent\n",
"[Container] 2021/06/11 08:26:17 Phases found in YAML: 2\n",
"[Container] 2021/06/11 08:26:17 BUILD: 1 commands\n",
"[Container] 2021/06/11 08:26:17 POST_BUILD: 0 commands\n",
"[Container] 2021/06/11 08:26:17 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase INSTALL\n",
"[Container] 2021/06/11 08:26:17 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase PRE_BUILD\n",
"[Container] 2021/06/11 08:26:17 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase BUILD\n",
"[Container] 2021/06/11 08:26:17 Running command python3.8 /opt/build.py --env $STAIRCASE_ENV --source $SOURCE_URL --id $BUNDLE_ID --host $HOST --api_key $X_API_KEY --bundle_type $BUNDLE_TYPE\n",
"npm WARN builder-api@1.0.0 No repository field.",
"Serverless: Excluding development dependencies...",
"Serverless: Injecting required Python packages to package...",
"Serverless: Updated AWS resource tags..",
"Health response code 403. Body b'\\nAccessDeniedInvalid date (should be seconds since epoch): 1623403526code-health-checker/metric/7ac245b7-2f93-485-8e8-abfdfd3b0a76P9ZDFS9GZNB3NYDJol1TYDYI/NgoC5uaxDld7Cii9sbSO4e+d+FK7G+FZJ2NwpZ40JgylLT60DiuSAwdQUQLbkNA1pc='",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Entering phase POST_BUILD\n",
"[Container] 2021/06/11 08:27:06 Running command if [ $CALLBACK_URL != \"null\" ]; then",
" if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" else\n",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" fi\n",
"fi",
"\n",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Expanding base directory path: .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding .\n",
"[Container] 2021/06/11 08:27:06 Expanding file paths for base directory .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding /output.json\n",
"[Container] 2021/06/11 08:27:06 Found 1 file(s)\n",
"[Container] 2021/06/11 08:27:06 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `build_id` required | `string` path | `7ac245b7-2f93-485-8e8-abfdfd3b0a76` | Unique build ID which was returned when build was started |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build ID which was returned when build was started |
| `status` | `string` | Build status (IN_PROGRESS, FAILED, SUCCEEDED) |
| `artifacts_url` | `string (url)` | Artifact URL if build was successfully completed |
| `logs` | `string[]` | Build Logs which can be used for build problem investigation |
| `metadata` | `object` | Metadata generated by build |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
##### Response `404``application/json`
1 fields
Build not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message which contains information about requested entity |
### Chat Bundle
`POST` `/chat`
#### Build Chat Bundle
`buildChatBundle`
Build Frontend Bundle
Build a deployable artifact for a chat bundle. The artifact must be provided via a URL. A callback will be sent to the URL specified in `callback_url` property.
##### Request
application/json Copy
```
{
"source_url": "https://code-manager-dev-root.s3.amazonaws.com/service-builder-api/2f867413-2f16-4c73-86ec-3086c0d4a33c/source.zip"
}
```
##### Response
201400
application/json Copy Build created
```
{
"build_id": "13bd5b51-1a41-4510-9baa-d7f7e24c89a3"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `source_url`required | `string (uri)` | Presigned URL to source code. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for build status |
| `env_variables` | `string` | Env variables, that is used in build process. |
##### Response `201``application/json`
1 fields
Build created
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build_id which can be used for tracking build status. Usually it is a UUID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
`GET` `/chat/{build_id}`
#### Retrieve Chat Bundle Build Status
`getChatBundleStatus`
Get build status for Chat bundles retrieves metadata generated by the build.
- Metadata is available only for builds that succeed (status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was built. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
- Regardless of status response contains build execution logs
##### Response
200400
application/json Copy 200 response
```
{
"build_id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"status": "SUCCEEDED",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:e5dcb19e-b025-4255-a42f-7f501456703c",
"timestamp": 1623399920.05132,
"version": "1.0.0",
"issuer": "https://build.staircaseapi.com/code-assessor",
"status": "SUCCEEDED"
},
"service-code": {
"id": "0da65dfd-9753-4bb4-8853-06e608979e73",
"timestamp": 1623399796.747468,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "c366156be0d8a39ce9a7bf85a5f5d5fc1a59ba4c",
"issuer": "https://build.staircaseapi.com/code"
},
"service-builder": {
"id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"timestamp": 1623400025.2152104,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://build.staircaseapi.com/infra-builder"
}
},
"artifacts_url": "https://builder-api-dev-codebuilddevbucket-kkwqngshvjap.s3.amazonaws.com/build-main/build/7ac245b7-2f93-485-8e8-abfdfd3b0a76/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1623405346",
"logs": [
"[Container] 2021/06/11 08:26:14 Waiting for agent ping\n",
"[Container] 2021/06/11 08:26:17 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 CODEBUILD_SRC_DIR=/codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2021/06/11 08:26:17 No commands found for phase name: post_build\n",
"[Container] 2021/06/11 08:26:17 Processing environment variables\n",
"[Container] 2021/06/11 08:26:17 Moving to directory /codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 Registering with agent\n",
"[Container] 2021/06/11 08:26:17 Phases found in YAML: 2\n",
"[Container] 2021/06/11 08:26:17 BUILD: 1 commands\n",
"[Container] 2021/06/11 08:26:17 POST_BUILD: 0 commands\n",
"[Container] 2021/06/11 08:26:17 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase INSTALL\n",
"[Container] 2021/06/11 08:26:17 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase PRE_BUILD\n",
"[Container] 2021/06/11 08:26:17 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase BUILD\n",
"[Container] 2021/06/11 08:26:17 Running command python3.8 /opt/build.py --env $STAIRCASE_ENV --source $SOURCE_URL --id $BUNDLE_ID --host $HOST --api_key $X_API_KEY --bundle_type $BUNDLE_TYPE\n",
"npm WARN builder-api@1.0.0 No repository field.",
"Serverless: Excluding development dependencies...",
"Serverless: Injecting required Python packages to package...",
"Serverless: Updated AWS resource tags..",
"Health response code 403. Body b'\\nAccessDeniedInvalid date (should be seconds since epoch): 1623403526code-health-checker/metric/7ac245b7-2f93-485-8e8-abfdfd3b0a76P9ZDFS9GZNB3NYDJol1TYDYI/NgoC5uaxDld7Cii9sbSO4e+d+FK7G+FZJ2NwpZ40JgylLT60DiuSAwdQUQLbkNA1pc='",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Entering phase POST_BUILD\n",
"[Container] 2021/06/11 08:27:06 Running command if [ $CALLBACK_URL != \"null\" ]; then",
" if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" else\n",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" fi\n",
"fi",
"\n",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Expanding base directory path: .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding .\n",
"[Container] 2021/06/11 08:27:06 Expanding file paths for base directory .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding /output.json\n",
"[Container] 2021/06/11 08:27:06 Found 1 file(s)\n",
"[Container] 2021/06/11 08:27:06 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `build_id` required | `string` path | `7ac245b7-2f93-485-8e8-abfdfd3b0a76` | Unique build ID which was returned when build was started |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build ID which was returned when build was started |
| `status` | `string` | Build status (IN_PROGRESS, FAILED, SUCCEEDED) |
| `artifacts_url` | `string (url)` | Artifact URL if build was successfully completed |
| `logs` | `string[]` | Build Logs which can be used for build problem investigation |
| `metadata` | `object` | Metadata generated by build |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
##### Response `404``application/json`
1 fields
Build not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message which contains information about requested entity |
### Data Bundle
`POST` `/data`
#### Build Data Bundle
`buildDataBundle`
Build a deployable artifact for a data bundle. The artifact must be provided via a URL. A callback will be sent to the URL specified in `callback_url` property. Build allows data bundle handlers to invoke IAM authorized endpoints by adding API execution policy.
##### Request
application/json Copy
```
{
"source_url": "https://code-manager-dev-root.s3.amazonaws.com/service-builder-api/2f867413-2f16-4c73-86ec-3086c0d4a33c/source.zip"
}
```
##### Response
201400
application/json Copy Build created
```
{
"build_id": "13bd5b51-1a41-4510-9baa-d7f7e24c89a3"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `source_url`required | `string (uri)` | Presigned URL to source code. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for build status |
| `custom_parameters` | `string` | Custom parameters, that is used in deployment process. Passed parameter is available in data bundler handler event object with key name 'CUSTOM_PARAMETERS'. Custom parameters have 4 KB size limit. |
| `serverless_version` | `string` | Serverless version, that is used in build process to update serverless framework version.`2.x``3.x`Example `3.x` |
##### Response `201``application/json`
1 fields
Build created
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build_id which can be used for tracking build status. Usually it is a UUID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
`GET` `/data/{build_id}`
#### Retrieve Data Bundle Build Status
`getDataBundleStatus`
Get build status for data bundles retrieves metadata generated by the build.
- Metadata is available only for builds that succeed (status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was built. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
- Regardless of status response contains build execution logs
##### Response
200400
application/json Copy 200 response
```
{
"build_id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"status": "SUCCEEDED",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:e5dcb19e-b025-4255-a42f-7f501456703c",
"timestamp": 1623399920.05132,
"version": "1.0.0",
"issuer": "https://build.staircaseapi.com/code-assessor",
"status": "SUCCEEDED"
},
"service-code": {
"id": "0da65dfd-9753-4bb4-8853-06e608979e73",
"timestamp": 1623399796.747468,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "c366156be0d8a39ce9a7bf85a5f5d5fc1a59ba4c",
"issuer": "https://build.staircaseapi.com/code"
},
"service-builder": {
"id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"timestamp": 1623400025.2152104,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://build.staircaseapi.com/infra-builder"
}
},
"artifacts_url": "https://builder-api-dev-codebuilddevbucket-kkwqngshvjap.s3.amazonaws.com/build-main/build/7ac245b7-2f93-485-8e8-abfdfd3b0a76/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1623405346",
"logs": [
"[Container] 2021/06/11 08:26:14 Waiting for agent ping\n",
"[Container] 2021/06/11 08:26:17 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 CODEBUILD_SRC_DIR=/codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2021/06/11 08:26:17 No commands found for phase name: post_build\n",
"[Container] 2021/06/11 08:26:17 Processing environment variables\n",
"[Container] 2021/06/11 08:26:17 Moving to directory /codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 Registering with agent\n",
"[Container] 2021/06/11 08:26:17 Phases found in YAML: 2\n",
"[Container] 2021/06/11 08:26:17 BUILD: 1 commands\n",
"[Container] 2021/06/11 08:26:17 POST_BUILD: 0 commands\n",
"[Container] 2021/06/11 08:26:17 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase INSTALL\n",
"[Container] 2021/06/11 08:26:17 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase PRE_BUILD\n",
"[Container] 2021/06/11 08:26:17 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase BUILD\n",
"[Container] 2021/06/11 08:26:17 Running command python3.8 /opt/build.py --env $STAIRCASE_ENV --source $SOURCE_URL --id $BUNDLE_ID --host $HOST --api_key $X_API_KEY --bundle_type $BUNDLE_TYPE\n",
"npm WARN builder-api@1.0.0 No repository field.",
"Serverless: Excluding development dependencies...",
"Serverless: Injecting required Python packages to package...",
"Serverless: Updated AWS resource tags..",
"Health response code 403. Body b'\\nAccessDeniedInvalid date (should be seconds since epoch): 1623403526code-health-checker/metric/7ac245b7-2f93-485-8e8-abfdfd3b0a76P9ZDFS9GZNB3NYDJol1TYDYI/NgoC5uaxDld7Cii9sbSO4e+d+FK7G+FZJ2NwpZ40JgylLT60DiuSAwdQUQLbkNA1pc='",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Entering phase POST_BUILD\n",
"[Container] 2021/06/11 08:27:06 Running command if [ $CALLBACK_URL != \"null\" ]; then",
" if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" else\n",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" fi\n",
"fi",
"\n",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Expanding base directory path: .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding .\n",
"[Container] 2021/06/11 08:27:06 Expanding file paths for base directory .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding /output.json\n",
"[Container] 2021/06/11 08:27:06 Found 1 file(s)\n",
"[Container] 2021/06/11 08:27:06 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `build_id` required | `string` path | `7ac245b7-2f93-485-8e8-abfdfd3b0a76` | Unique build ID which was returned when build was started |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build ID which was returned when build was started |
| `status` | `string` | Build status (IN_PROGRESS, FAILED, SUCCEEDED) |
| `artifacts_url` | `string (url)` | Artifact URL if build was successfully completed |
| `logs` | `string[]` | Build Logs which can be used for build problem investigation |
| `metadata` | `object` | Metadata generated by build |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
##### Response `404``application/json`
1 fields
Build not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message which contains information about requested entity |
### Frontend Bundle
`POST` `/frontend`
#### Build Frontend Bundle
`buildFrontendBundle`
Build a deployable artifact for a frontend bundle. The artifact must be provided via a URL. A callback will be sent to the URL specified in `callback_url` property.
##### Request
application/json Copy
```
{
"source_url": "https://code-manager-dev-root.s3.amazonaws.com/service-builder-api/2f867413-2f16-4c73-86ec-3086c0d4a33c/source.zip"
}
```
##### Response
201400
application/json Copy Build created
```
{
"build_id": "13bd5b51-1a41-4510-9baa-d7f7e24c89a3"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `source_url`required | `string (uri)` | Presigned URL to source code. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for build status |
| `env_variables` | `string` | Env variables, that is used in build process. |
##### Response `201``application/json`
1 fields
Build created
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build_id which can be used for tracking build status. Usually it is a UUID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
`GET` `/frontend/{build_id}`
#### Retrieve Frontend Bundle Build Status
`getFrontendBundleStatus`
Get build status for fronend bundles retrieves metadata generated by the build.
- Metadata is available only for builds that succeed (status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was built. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
- Regardless of status response contains build execution logs
##### Response
200400
application/json Copy 200 response
```
{
"build_id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"status": "SUCCEEDED",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:e5dcb19e-b025-4255-a42f-7f501456703c",
"timestamp": 1623399920.05132,
"version": "1.0.0",
"issuer": "https://build.staircaseapi.com/code-assessor",
"status": "SUCCEEDED"
},
"service-code": {
"id": "0da65dfd-9753-4bb4-8853-06e608979e73",
"timestamp": 1623399796.747468,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "c366156be0d8a39ce9a7bf85a5f5d5fc1a59ba4c",
"issuer": "https://build.staircaseapi.com/code"
},
"service-builder": {
"id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"timestamp": 1623400025.2152104,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://build.staircaseapi.com/infra-builder"
}
},
"artifacts_url": "https://builder-api-dev-codebuilddevbucket-kkwqngshvjap.s3.amazonaws.com/build-main/build/7ac245b7-2f93-485-8e8-abfdfd3b0a76/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1623405346",
"logs": [
"[Container] 2021/06/11 08:26:14 Waiting for agent ping\n",
"[Container] 2021/06/11 08:26:17 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 CODEBUILD_SRC_DIR=/codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2021/06/11 08:26:17 No commands found for phase name: post_build\n",
"[Container] 2021/06/11 08:26:17 Processing environment variables\n",
"[Container] 2021/06/11 08:26:17 Moving to directory /codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 Registering with agent\n",
"[Container] 2021/06/11 08:26:17 Phases found in YAML: 2\n",
"[Container] 2021/06/11 08:26:17 BUILD: 1 commands\n",
"[Container] 2021/06/11 08:26:17 POST_BUILD: 0 commands\n",
"[Container] 2021/06/11 08:26:17 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase INSTALL\n",
"[Container] 2021/06/11 08:26:17 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase PRE_BUILD\n",
"[Container] 2021/06/11 08:26:17 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase BUILD\n",
"[Container] 2021/06/11 08:26:17 Running command python3.8 /opt/build.py --env $STAIRCASE_ENV --source $SOURCE_URL --id $BUNDLE_ID --host $HOST --api_key $X_API_KEY --bundle_type $BUNDLE_TYPE\n",
"npm WARN builder-api@1.0.0 No repository field.",
"Serverless: Excluding development dependencies...",
"Serverless: Injecting required Python packages to package...",
"Serverless: Updated AWS resource tags..",
"Health response code 403. Body b'\\nAccessDeniedInvalid date (should be seconds since epoch): 1623403526code-health-checker/metric/7ac245b7-2f93-485-8e8-abfdfd3b0a76P9ZDFS9GZNB3NYDJol1TYDYI/NgoC5uaxDld7Cii9sbSO4e+d+FK7G+FZJ2NwpZ40JgylLT60DiuSAwdQUQLbkNA1pc='",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Entering phase POST_BUILD\n",
"[Container] 2021/06/11 08:27:06 Running command if [ $CALLBACK_URL != \"null\" ]; then",
" if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" else\n",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" fi\n",
"fi",
"\n",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Expanding base directory path: .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding .\n",
"[Container] 2021/06/11 08:27:06 Expanding file paths for base directory .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding /output.json\n",
"[Container] 2021/06/11 08:27:06 Found 1 file(s)\n",
"[Container] 2021/06/11 08:27:06 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `build_id` required | `string` path | `7ac245b7-2f93-485-8e8-abfdfd3b0a76` | Unique build ID which was returned when build was started |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build ID which was returned when build was started |
| `status` | `string` | Build status (IN_PROGRESS, FAILED, SUCCEEDED) |
| `artifacts_url` | `string (url)` | Artifact URL if build was successfully completed |
| `logs` | `string[]` | Build Logs which can be used for build problem investigation |
| `metadata` | `object` | Metadata generated by build |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
##### Response `404``application/json`
1 fields
Build not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message which contains information about requested entity |
### Frontend Config Bundle
`POST` `/frontend-config`
#### Build Frontend Config Bundle
`buildFrontendConfigBundle`
Build a deployable artifact for a frontend config bundle. The artifact must be provided via a URL. A callback will be sent to the URL specified in `callback_url` property.
##### Request
application/json Copy
```
{
"source_url": "https://code-manager-dev-root.s3.amazonaws.com/service-builder-api/2f867413-2f16-4c73-86ec-3086c0d4a33c/source.zip"
}
```
##### Response
201400
application/json Copy Build created
```
{
"build_id": "13bd5b51-1a41-4510-9baa-d7f7e24c89a3"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `source_url`required | `string (uri)` | Presigned URL to source code. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for build status |
| `env_variables` | `string` | Env variables, that is used in build process. |
##### Response `201``application/json`
1 fields
Build created
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build_id which can be used for tracking build status. Usually it is a UUID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
`GET` `/frontend-config/{build_id}`
#### Retrieve Frontend Config Bundle Build Status
`getFrontendConfigBundleStatus`
Get build status for Frontend Config bundles retrieves metadata generated by the build.
- Metadata is available only for builds that succeed (status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was built. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
- Regardless of status response contains build execution logs
##### Response
200400
application/json Copy 200 response
```
{
"build_id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"status": "SUCCEEDED",
"metadata": {
"service-assessor": {
"id": "devops-code-assessor:e5dcb19e-b025-4255-a42f-7f501456703c",
"timestamp": 1623399920.05132,
"version": "1.0.0",
"issuer": "https://build.staircaseapi.com/code-assessor",
"status": "SUCCEEDED"
},
"service-code": {
"id": "0da65dfd-9753-4bb4-8853-06e608979e73",
"timestamp": 1623399796.747468,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "c366156be0d8a39ce9a7bf85a5f5d5fc1a59ba4c",
"issuer": "https://build.staircaseapi.com/code"
},
"service-builder": {
"id": "7ac245b7-2f93-485-8e8-abfdfd3b0a76",
"timestamp": 1623400025.2152104,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://build.staircaseapi.com/infra-builder"
}
},
"artifacts_url": "https://builder-api-dev-codebuilddevbucket-kkwqngshvjap.s3.amazonaws.com/build-main/build/7ac245b7-2f93-485-8e8-abfdfd3b0a76/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1623405346",
"logs": [
"[Container] 2021/06/11 08:26:14 Waiting for agent ping\n",
"[Container] 2021/06/11 08:26:17 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2021/06/11 08:26:17 CODEBUILD_SRC_DIR=/codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2021/06/11 08:26:17 No commands found for phase name: post_build\n",
"[Container] 2021/06/11 08:26:17 Processing environment variables\n",
"[Container] 2021/06/11 08:26:17 Moving to directory /codebuild/output/src212027353/src\n",
"[Container] 2021/06/11 08:26:17 Registering with agent\n",
"[Container] 2021/06/11 08:26:17 Phases found in YAML: 2\n",
"[Container] 2021/06/11 08:26:17 BUILD: 1 commands\n",
"[Container] 2021/06/11 08:26:17 POST_BUILD: 0 commands\n",
"[Container] 2021/06/11 08:26:17 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase INSTALL\n",
"[Container] 2021/06/11 08:26:17 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase PRE_BUILD\n",
"[Container] 2021/06/11 08:26:17 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:26:17 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:26:17 Entering phase BUILD\n",
"[Container] 2021/06/11 08:26:17 Running command python3.8 /opt/build.py --env $STAIRCASE_ENV --source $SOURCE_URL --id $BUNDLE_ID --host $HOST --api_key $X_API_KEY --bundle_type $BUNDLE_TYPE\n",
"npm WARN builder-api@1.0.0 No repository field.",
"Serverless: Excluding development dependencies...",
"Serverless: Injecting required Python packages to package...",
"Serverless: Updated AWS resource tags..",
"Health response code 403. Body b'\\nAccessDeniedInvalid date (should be seconds since epoch): 1623403526code-health-checker/metric/7ac245b7-2f93-485-8e8-abfdfd3b0a76P9ZDFS9GZNB3NYDJol1TYDYI/NgoC5uaxDld7Cii9sbSO4e+d+FK7G+FZJ2NwpZ40JgylLT60DiuSAwdQUQLbkNA1pc='",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Entering phase POST_BUILD\n",
"[Container] 2021/06/11 08:27:06 Running command if [ $CALLBACK_URL != \"null\" ]; then",
" if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" else\n",
" curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'",
" fi\n",
"fi",
"\n",
"\n",
"[Container] 2021/06/11 08:27:06 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n",
"[Container] 2021/06/11 08:27:06 Expanding base directory path: .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding .\n",
"[Container] 2021/06/11 08:27:06 Expanding file paths for base directory .\n",
"[Container] 2021/06/11 08:27:06 Assembling file list\n",
"[Container] 2021/06/11 08:27:06 Expanding /output.json\n",
"[Container] 2021/06/11 08:27:06 Found 1 file(s)\n",
"[Container] 2021/06/11 08:27:06 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2021/06/11 08:27:06 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `build_id` required | `string` path | `7ac245b7-2f93-485-8e8-abfdfd3b0a76` | Unique build ID which was returned when build was started |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `build_id` | `string (uuid)` | Unique build ID which was returned when build was started |
| `status` | `string` | Build status (IN_PROGRESS, FAILED, SUCCEEDED) |
| `artifacts_url` | `string (url)` | Artifact URL if build was successfully completed |
| `logs` | `string[]` | Build Logs which can be used for build problem investigation |
| `metadata` | `object` | Metadata generated by build |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message in string or object format |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message in string format |
| `url` | `string (url)` | URL with link to page with information how this issue can be resolved |
##### Response `404``application/json`
1 fields
Build not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message which contains information about requested entity |
## Errors
`400``403``404`
## More in Shipping
- Previous product: Assess
- Next product: Code
---
# Code
# Code
Repository operations as an API: clone, branch, commit, pull request and secret handling, as the first pipeline stage.
The pipeline starts by acting on the repository, and it does that through an API rather than through shell steps embedded in a build definition. Cloning at a pinned commit, opening a branch, committing generated output and raising a pull request are all calls.
That is what makes generation practical. A configuration bundle produced by a generator can be committed and proposed by the same pipeline that will build it.
## Operations
### Branch
`POST` `/branches`
#### Retrieve List of Branches per Repository
`getBranch`
List the name of branches in a repository
This service retrieves a list of names of branches in a given repository and project.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
```
##### Response
202400401403404405
application/json Copy List the branches of a given repository
```
{
"branches": [
"master",
"developer",
"qa"
],
"default_branch": "master"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or account not found.
```
{
"message": "Not found. Either repository_name, branch or commits are not found"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. settings/Personal access token/New/Enable SSO. |
##### Response `202``application/json`
2 fields
List the branches of a given repository
| Field | Type | Description |
| --- | --- | --- |
| `branches` | `string[]` | List of branches of repository |
| `default_branch` | `string` | Default branch of repository |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or account not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Clone
`POST` `/clone`
#### Clone Repository
`cloneRepository`
Clone code
This service clones code for a given repository and branch. The service returns a bundle_id that can be used to check the status and result of the request.
The cloned code is persisted as a .zip file in the Staircase persistence layer.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"branch": "master",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez"
}
```
##### Response
202400401403404405
application/json Copy Clone job started
```
{
"bundle_id": "979a6aa8-4f2-400d-9451-80ee1e127485"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or branch is not found.
```
{
"message": "Not found. Either repository_name or branch is not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository to be cloned |
| `branch` | `string` | Name of GitHub branch |
| `commit_sha` | `string` | Commit SHA |
| `github_account` | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. Go to settings/Personal access token/New/Enable SSO. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for code status |
##### Response `202``application/json`
1 fields
Clone job started
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | Bundle id of the cloned project |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or branch is not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`GET` `/clone/{bundle_id}`
#### Retrieve Clone Status
`cloneBundle`
This service retrieves the status of a Clone Code request for a given bundle_id. Status = IN_PROGRESS, SUCCEEDED, or FAILED. Continue to ping this service until you receive a status = SUCCEEDED.
Retrieve Clone Status returns a source URL.
The source URL is a presigned URL for the new cloned code package. Provide the source URL as a parameter to the Build Bundle service.
##### Response
200400403404405
application/json Copy Clone status
```
{
"bundle_id": "979a6aa8-4f2-400d-9451-80ee1e127485",
"clone_status": "SUCCEEDED",
"commit_hash": "80a6e06179b267f0f4da68a2e1707d17b8f77fb2",
"source_url": "https://code-dev-025.s3.amazonaws.com/service-builder-api/979a6aa8/source.zip",
"metadata": {
"service-code": {
"commit_hash": "979a6aa8-4f2-400d-9451-80ee1e127485",
"id": "d898b987-eda3-4b75-b7e7-bea8ae39674c",
"issuer": "https://api.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1611603369.1289215,
"version": 1.1,
"repository_name": "StaircaseAPI/code"
}
}
}
```
application/json Copy Bad syntax
```
{
"message": "Bad syntax"
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Clone job not found.
```
{
"message": "Clone job not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `bundle_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | bundle id of the cloned project |
##### Response `200``application/json`
5 fields
Clone status
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | ID returned by **Clone Code** |
| `clone_status` | `string` | IN_PROGRESS, FAILED, or SUCCEEDED`FAILED``IN_PROGRESS``SUCCEEDED` |
| `commit_hash` | `string (uuid)` | The branch last commit hash when clone was completed. |
| `metadata` | `object` | Metadata included in presigned URL with the clone status information |
| `source_url` | `string (uri)` | Presigned URL for the new cloned code package and metadata with information about the clone. |
##### Response `400``application/json`
1 fields
Bad syntax
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Clone job not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Repository
`POST` `/repos`
#### Create repository
`createRepository`
This service creates repository in given organization.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"private": true,
"visibility": "private",
"gitignore_template": "Python",
"description": "Repository description"
}
```
##### Response
202400401403404405
application/json Copy Repository created
```
{
"status": "Succeeded",
"repo_url": "https://"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or account not found.
```
{
"message": "Not found. Either repository_name, branches or secret"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. settings/Personal access token/New/Enable SSO. |
| `private` | `string` | Whether the GitHub repository is private |
| `visibility` | `string` | Visibility level of the GitHub repository |
| `description` | `string` | Description of the GitHub Repository |
| `gitignore_template` | `string` | Template name for git ignore file. For more information please visit GitHub git ignore collection pageExample `Python` |
##### Response `202``application/json`
2 fields
Repository created
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the pull request creation |
| `repo_url` | `string` | Created repository URL |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or account not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Secret
`POST` `/secret`
#### Create or Update Repository Secret
`updateSecret`
Create or update a secret
This service create or update a secret in a given repository
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"secret_name": "newsecret",
"secret_value": "0d1357"
}
```
##### Response
202400401403404405
application/json Copy The secret was updated or created
```
{
"message": "Succeeded"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or account not found.
```
{
"message": "Not found. Either repository_name, branches or secret"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `github_account` | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. Go to settings/Personal access token/New/Enable SSO. |
| `secret_name` | `string` | The name of the secret |
| `secret_value` | `string` | The value of the secret |
##### Response `202``application/json`
1 fields
The secret was updated or created
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | status |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or account not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`POST` `/remove-secret`
#### Delete Repository Secret
`removeSecret`
Delete a secret
This service deletes a secret in a given repository
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"secret_name": "newsecret"
}
```
##### Response
202400401403404405
application/json Copy The secret was deleted
```
{
"message": "Succeeded"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or account not found.
```
{
"message": "Not found. Either repository_name, branches or secret"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository to be cloned |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. settings/Personal access token/New/Enable SSO. |
| `secret_name`required | `string` | The name of the secret |
##### Response `202``application/json`
1 fields
The secret was deleted
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | status |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or account not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Commit
`POST` `/commits`
#### Retrieve List of Commits per Branch
`getCommit`
List of a branch commit history
This service retrieves a list of the last of 14 days commits history from a given repository and branch, start date and end date can be given, the difference between the two cannot surpass 14 days. The service returns a list of commits objects with a maximum of 30 . By default, it will return a list of the last 14 days of commits with a maximum response of 30. Next_token can be used to retrieve the next 30 commits until is null.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"branch": "master",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"start_date": "2021-01-05",
"end_date": "2021-01-15",
"next_token": 1
}
```
##### Response
202400401403404405
application/json Copy Clone job started
```
{
"commits": [
{
"comments": "First commit",
"author": "bezos",
"date": "2021-01-29T16:55:51Z"
},
{
"comments": "Second commit",
"author": "jeff",
"date": "2021-01-29T16:25:51Z"
}
],
"next_token": 0
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name, branch or commits are not found.
```
{
"message": "Not found. Either repository_name, branch or commits are not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `branch` | `string` | Name of GitHub branch |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. Go to settings/Personal access token/New/Enable SSO. |
| `start_date` | `string` | Minimum date in time that will be returned in this format "YYYY-MM-DD" |
| `end_date` | `string` | Maximum date in time that will be returned in this format "YYYY-MM-DD" |
| `next_token` | `integer` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
##### Response `202``application/json`
3 fields
Clone job started
| Field | Type | Description |
| --- | --- | --- |
| `commits` | `object[]` | List of commits of branch. |
| `comment` | `string` | Comment |
| `author` | `string` | Author name |
| `date` | `string` | Date |
| `pagination` | `integer` | Pagination number |
| `totalSize` | `integer` | Total number of commits in the branch |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name, branch or commits are not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`POST` `/commits/change`
#### Commit changes to new branch
`commitChange`
This service commits changes provided in zip file by creating new branch from main branch. Zip file should contain git ignore file.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"new_branch": "feature-branch",
"user_email": "user@email.com",
"user_name": "User Name",
"zip_url": "https://bucket.s3.amazonaws.com/repo.zip?AWSAccessKeyId=&Signature="
}
```
##### Response
202400401403404405
application/json Copy Commit operation job started
```
{
"operation_id": "704db6f3-c534-4c4b-b7dd-d4fa52d60e71"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name, branch or commits are not found.
```
{
"message": "Not found. Either repository_name, branch or commits are not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
9 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. Go to settings/Personal access token/New/Enable SSO. |
| `new_branch`required | `string` | Name of branch that will be created |
| `commit_message` | `string` | Commit message for changes |
| `user_email`required | `string` | Git user email. The email address used in the author identity when creating commit. |
| `user_name`required | `string` | Git username. The human-readable name used in the author identity when creating commit. |
| `zip_url`required | `string` | Pre-signed URL that will be used for getting repository zip file. |
| `callback_url` | `string (uri)` | Callback URL where are you waiting for commit status |
##### Response `202``application/json`
1 fields
Commit operation job started
| Field | Type | Description |
| --- | --- | --- |
| `operation_id` | `string` | Operation ID of started asynchronous job. |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name, branch or commits are not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`GET` `/commits/change/{operation_id}`
#### Retrieve Commit Changes Status
`getCommitChangeStatus`
Retrieve Commit Change Status
This service retrieves the status of a Commit Change request for a given operation_id. Status = REQUEST_MADE, IN_PROGRESS, SUCCEEDED, or FAILED.
##### Response
200400403404405
application/json Copy Clone status
```
{
"status": "SUCCEEDED"
}
```
application/json Copy Bad syntax
```
{
"message": "Bad syntax"
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Commit change operation not found.
```
{
"message": "Commit change operation not found."
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `operation_id` required | `string` path | `979a6aa8-4f2-400d-9451-80ee1e127485` | operation id of the started commit change job |
##### Response `200``application/json`
1 fields
Clone status
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | REQUEST_MADE, IN_PROGRESS, FAILED, or SUCCEEDED`FAILED``IN_PROGRESS``REQUEST_MADE``SUCCEEDED` |
##### Response `400``application/json`
1 fields
Bad syntax
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Commit change operation not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Pull Request
`POST` `/pull-request`
#### Create Pull Request
`pullRequest`
Create pull request
This service creates pull request. Reviewers field is optional for adding reviewer to pull request. Author of the pull request can not be added as a reviewer.
#### Warning
`project_name` can still be used instead of `repository_name` but is to be deprecated in the future.
##### Request
application/json Copy
```
{
"repository_name": "code",
"github_account": "staircaseapi",
"github_token": "a50d135781d8c9ca26884ab0a858205d74f726ez",
"head": "head",
"base": "base",
"title": "title",
"body": "body"
}
```
##### Response
202400401403404405
application/json Copy Pull request created
```
{
"message": "Succeeded"
}
```
application/json Copy Bad request syntax or missed a required field
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Unauthorized, Bad credentials.
```
{
"message": "Unauthorized, Bad credentials."
}
```
application/json Copy Bad request syntax or forbidden request
```
{
"message": "Bad request syntax or missed a required field"
}
```
application/json Copy Not found. Either repository_name or account not found.
```
{
"message": "Not found. Either repository_name, branches or secret"
}
```
application/json Copy Method not allowed.
```
{
"message": "The method is not allowed for the requested URL"
}
```
##### Request body`application/json`
8 fields
| Field | Type | Description |
| --- | --- | --- |
| `repository_name`required | `string` | Name of the GitHub repository |
| `github_account`required | `string` | GitHub account name |
| `github_token`required | `string` | GitHub token. settings/Personal access token/New/Enable SSO. |
| `head`required | `string` | The name of the branch where your changes are implemented. |
| `base`required | `string` | The name of the branch you want the changes pulled into. |
| `title`required | `string` | The title of the new pull request |
| `body` | `string` | The contents of the pull request |
| `reviewers` | `string[]` | List of reviewers for pull request |
##### Response `202``application/json`
2 fields
Pull request created
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the pull request creation |
| `pr_url` | `string` | Created pull request URL |
##### Response `400``application/json`
1 fields
Bad request syntax or missed a required field
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `401``application/json`
1 fields
Unauthorized, Bad credentials.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Bad request syntax or forbidden request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found. Either repository_name or account not found.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `405``application/json`
1 fields
Method not allowed.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Operations
`POST` `/`
#### Post operation
`post-operation`
Description
##### Request
application/json Copy
```
{
"test": "test"
}
```
##### Response
application/json Copy 200 response
```
{
"assessment_id": "devops-code-assessor:9dff4dc3-f700-4fc8-a51a-56d91d7ed7df"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `test1` required | `string` header | `Test1` | Authorization key |
| `x-api-key` required | `string` header | `Test1` | Authorization key |
| `test` | `string` header | `Test` | test key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `test` | `object[]` | Errors array |
| `message` | `string` | Error message |
| `path` | `string` | Description |
| `errors` | `object` | Contains errors on failed assessment |
| `errors` | `object` | Errors1 |
| `errors2` | `string` | Errors2 |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `assessment_id` | `string` | Assessment id, used for get assessment status |
##### Other responses
`204``400`
## Errors
`400``401``403``404``405``422`
## More in Shipping
- Previous product: Build
- Next product: Comply
---
# Comply
# Comply
Compliance evidence generated by the pipeline that ships the code: control status against named standards, and a secure workspace for remote access.
Comply checks source code and infrastructure against committed control sets — `NIST`, `PCI`, `SOC 2` and `HIPAA` among them — and reports misconfigurations and violations in near real time rather than at review time.
Findings are broadcast into Health, so a configuration that drifts out of policy surfaces in the same place an operator is already watching, and can be corrected there.
## How it works
It also provides the secure workspace an engineer outside the United States works from to reach the cloud console and the product APIs, and it is the path that issues temporary maintenance credentials after the environment owner approves the request.
Evidence is generated continuously because the alternative measures a moment. A control verified once a year has an unknown state between verifications, and that gap is exactly where drift lives.
Comply is callable on its own as well as being a pipeline stage, which is what lets an environment be assessed without a deployment.
## Operations
### Audit
`POST` `/audit/vanta_role`
#### Create Vanta Role
`create-vanta-role`
Create vanta role
Create vanta role creates a role to integrate your environment with vanta.com, an application for security audit. This service output an arn role that can be used inside vanta application to give vanta access to audit your environment.
This service assumes that you have a vanta account, and you are aware of the external_id and account_id associated with that account.
##### Request
application/json Copy
```
{
"external_id": "BA51515716F989E",
"account_id": "956993596393"
}
```
##### Response
application/json Copy 200 response
```
{
"vanta_role_arn": "arn:aws:iam::891306488523:role/vanta-auditor-202d30c9-06ce-4de0-889a-a17721d670d0"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `external_id`required | `string` | External id from vanta.com |
| `account_id`required | `string` | Account id from vanta.com |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `vanta_role_arn` | `string` | Vanta role arn which can be added to vanta to start auditing your environment |
##### Other responses
`400``401``403``404`
`DELETE` `/audit/vanta_role/{role_name}`
#### Delete Vanta Role
`delete-vanta-role`
Delete vanta role
Delete vanta role deletes an existing role for vanta.com by name, you can get the role name by using the service Retrieve Vanta Roles
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `role_name` required | `string` path | `vanta-auditor-addg9e54-53dd-48aa-bad1-82762a05ab44` | Role name for vanta.com |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Response status |
##### Other responses
`400``401``403``404`
`GET` `/audit/vanta_roles`
#### Retrieve Vanta Roles
`retrieve-vanta-role`
Retrieve vanta roles retrieves a list of roles created to integrate your environment with vanta.com
##### Response
application/json Copy 200 response
```
{
"vanta_roles": [
{
"role_name": "vanta-auditor-ee373866-5447-435f-b4e0-43390de1392a",
"vanta_role_arn": "arn:aws:iam::791306477523:role/vanta-auditor/vanta-auditor-ee373866-5447-435f-b4e0-43390de1392a",
"account_id": "956993596390",
"external_id": "BA51515716F989F"
}
]
}
```
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `vanta_roles` | `object[]` | Vanta roles |
| `role_name` | `string` | Auto-generated role name |
| `vanta_role_arn` | `string` | Vanta role arn which can be added to vanta.com |
| `account_id` | `string` | Account id from vanta.com |
| `external_id` | `string` | External id from vanta.com |
##### Other responses
`400``401``403``404`
`PUT` `/audit/cloudtrail`
#### Set Cloudtrail Status
`set-cloudtrail-status`
Set cloudtrail status
Set cloudtrail status enables and disables the generation of the cloudtrail logs which are necessary to meet security requirements for vanta.com
##### Request
Disabling cloudtrailEnabling cloudtrail
application/json Copy
```
{
"cloudtrail_enabled": "false"
}
```
application/json Copy
```
{
"cloudtrail_enabled": "true"
}
```
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `cloudtrail_enabled`required | `string` | Cloudtrail logs status |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Response status |
##### Other responses
`400``401``403``404`
### Workspace
`GET` `/bundles`
#### Retrieve Bundles
`get-workspace-bundles`
Retrieve workspaces bundles Retrieves a list that describes the available WorkSpace bundles.
##### Response
application/json Copy 200 response
```
{
"Bundles": [
{
"BundleID": "ws-8kvnwmhz4",
"Name": "Bundle name",
"Description": "Description"
}
]
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `123456` | The token to use to retrieve the next page of results. This value is null when there are no more results to return. |
| `owner` | `string` query | `123456` | To describe the bundles provided by Amazon Web Services, specify AMAZON. To describe the bundles that belong to your account, don't specify a value. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `Bundles` | `object[]` | Array of workspaces Bundles information |
##### Other responses
`400``401``403``404``422`
`POST` `/bundles`
#### Create Bundles
`create-bundles`
Create bundles
'Create image Creates the specified WorkSpace bundle. For more information about creating WorkSpace bundles, see Create a Custom WorkSpaces Image and Bundle.'
##### Request
application/json Copy
```
{
"name": "DefaultBundle",
"description": "Default Bundle",
"image_id": "wsb-gk1wpk43z",
"compute_type": "STANDARD",
"user_storage": "5",
"root_storage": "5"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "The bundle is being created."
}
```
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | The name of the bundle. |
| `description`required | `string` | The description of the bundle. |
| `image_id`required | `string` | The identifier of the image that is used to create the bundle. |
| `compute_type`required | `string` | Describes the computed type of the bundle. |
| `user_storage`required | `string` | The size of the user volume. |
| `root_storage`required | `string` | The size of the root volume. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message about the creation |
##### Other responses
`400``401``403``404``422`
`PUT` `/default-bundle`
#### Update Default Bundle
`update-default-bundle`
Update default bundle
'Update default bundle Updates the default bundle that will be used when creating workspaces'
##### Request
application/json Copy
```
{
"budnle_id": "wsb-gk1wpk43z"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "Succeeded"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id`required | `string` | The identifier of the bundle for the WorkSpace. You can use DescribeWorkspaceBundles to list the available bundles. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message about the creation |
##### Other responses
`400``401``403``404``422`
`GET` `/images`
#### Retrieve Images
`get-workspace-images`
Retrieve workspaces images Retrieves a list that describes one or more images.
##### Response
application/json Copy 200 response
```
{
"Images": [
{
"ImageID": "ws-8kvnwmhz4",
"Name": "Image name",
"Description": "Description"
}
]
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `123456` | The token to use to retrieve the next page of results. This value is null when there are no more results to return. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `Images` | `object[]` | Array of workspaces images information |
##### Other responses
`400``401``403``404``422`
`POST` `/images`
#### Create Image
`create-image`
Create image Creates a new updated WorkSpace image based on the specified source image.
##### Request
application/json Copy
```
{
"bundle_id": "wsb-gk1wpk43z",
"name": "DefaultImage",
"description": "Default image"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "The image is being created."
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string` | The identifier of the bundle for the WorkSpace. You can use DescribeWorkspaceBundles to list the available bundles. |
| `description` | `string` | A description of whether updates for the WorkSpace image are available. |
| `name`required | `string` | The name of the new updated WorkSpace image. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message about the creation |
##### Other responses
`400``401``403``404``422`
`POST` `/workspace`
#### Create Workspace
`create-workspace`
Create workspace creates a workspace for the user provided.
##### Request
Create a default workspaceCreate a custom workspace
application/json Copy
```
{
"given_name": "Given Name",
"surname": "Surname"
}
```
application/json Copy
```
{
"bundle_id": "wsb-gk1wpk43z",
"given_name": "Given Name",
"surname": "Surname"
}
```
##### Response
200422
application/json Copy 200 response
```
{
"message": "The workspace is being created. The user will receive and email with instructions and information about the workspace."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "The entity can not be processed."
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string` | The identifier of the bundle for the WorkSpace. You can use DescribeWorkspaceBundles to list the available bundles. |
| `given_name`required | `string` | The given name of the user the workspace will be created for. |
| `surname`required | `string` | The surname of the user the workspace will be created for. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message about the creation of the workspace |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `message`required | `string` | Error description. |
##### Other responses
`400``401``403``404`
`DELETE` `/workspace/{workspace_id}`
#### Delete Workspace
`delete-workspace`
Delete workspace deletes a workspace and its associated user.
##### Response
200422 Not existent422 Missing id422 Rippling synchronization422 Deletion disabled422 application/json
application/json Copy 200 response
```
{
"message": "Workspace deletion has started."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "The workpsace does not exist."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "Workspace id must be provided."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "This workspace can only be deleted via Rippling automated synchronization."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "Workspace creation/deletion is disabled."
}
```
application/json Copy Unprocessable Entity
```
{
"message": "The entity can not be processed."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `workspace_id` required | `string` path | `ws-cv8hqyrjr` | Id of the workspace that will be deleted. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `message`required | `string` | Error description. |
##### Other responses
`400``401``403``404`
`PUT` `/workspace/{workspace_id}`
#### Update Workspace
`update-workspace`
Update workspace Update a workspace compute type. Compute type payload attribute can have the following values:
- VALUE [1 CPU, 2 GB Memory, 80|10 GB root|user storage]
- STANDARD [2 CPU, 4 GB Memory, 80|50 GB root|user storage]
- PERFORMANCE [2 CPU, 7.5 GB Memory, 80|100 GB root|user storage]
- POWER [4 CPU, 16 GB Memory, 175|100 GB root|user storage]
- POWERPRO [8 CPU, 32 GB Memory, 175|100 GB root|user storage]
- GRAPHICS [8 CPU, 15 GB Memory, 100|100 GB root|user storage]
- GRAPHICSPRO [16 CPU, 122 GB Memory, 100|100 GB root|user storage]
##### Request
application/json Copy
```
{
"compute_type": "VALUE"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "Workspace update has started."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `workspace_id` required | `string` path | `ws-cv8hqyrjr` | Id of the workspace that will be updated. |
| `Authorization` required | `string` header | `` | Authorization token. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `compute_type` | `string` | Compute type. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The status message |
##### Other responses
`400``401``403``404`
`POST` `/workspace/reset-password`
#### Reset Password
`reset-workspace-password`
Reset Password set new password using authorized credentials
##### Request
application/json Copy
```
{
"token": "123"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "Succeeded."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `new_password` | `string` | New password. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message describing process. |
##### Other responses
`400``401``403``404``422`
`GET` `/workspaces`
#### Retrieve Workspaces
`get-workspace`
Retrieve workspaces returns a list of workspaces.
##### Response
200422
application/json Copy 200 response
```
{
"Workspaces": {
"WorkspaceId": "ws-8kvnwmhz4",
"DirectoryId": "d-90675e3e71",
"UserName": "efrain.coello",
"IpAddress": "10.1.0.137",
"State": "STOPPED",
"BundleId": "wsb-gk1wpk43z",
"SubnetId": "subnet-034c07dc6446907de",
"ComputerName": "WSAMZN-4M9H1COV"
}
}
```
application/json Copy Unprocessable Entity
```
{
"message": "The entity can not be processed."
}
```
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `Workspaces` | `object[]` | Array of workspaces information |
##### Response `422``application/json`
1 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unprocessable entity error. |
| `message`required | `string` | Error description. |
##### Other responses
`400``401``403``404`
`POST` `/compliance_metrics`
#### Trigger Rippling Synchronization
`trigger-rippling-sync`
Trigger rippling synchronization starts the synchronization with Rippling. The token is validated against Rippling. If the token is valid the synchronization is triggered but, the token is not saved for the scheduled synchronization calls.
##### Request
application/json Copy
```
{
"rippling_token": "73ghdygye737YTY73euyetdyydu73587ksjeifhyYGDJ"
}
```
##### Response
200400
application/json Copy 200 response
```
{
"message": "Successfully started rippling synchronization."
}
```
application/json Copy Bad Request
```
{
"message": "Rippling token provided is invalid."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `rippling_token`required | `string` | Rippling token that should match the token used for the Rippling synchronization |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response status |
##### Response `400``application/json`
1 fields
Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error description. |
##### Other responses
`401``403``404`
### Compliance
`POST` `/compliance`
#### Create Compliance
`new-compliance`
Comply looks for security violations based on security rules of comply for a given product.
Comply returns an compliance_id in the response body. To retrieve the results of the security validation, call Retrieve Compliance Status with the compliance_id.
Requirements to pass comply.
1. The name of your project in asana must be the same as the product ontology. 2 Get your asana token here ``````.
1. Add the custom field "Github" to your asana project.
1. Add the link to your pull request in asana task custom field "Github" field.
1. The task must be in the column "In progress" of asana.
##### Request
application/json Copy
```
{
"source_url": "https://code-dev-0258.s3.amazonaws.com/code-comply/1506dbf2/source.zip?AWSAccessKeyId=2323",
"product_name": "Comply"
}
```
##### Response
application/json Copy 200 response
```
{
"compliance_id": "9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `asana_token` required | `string` header | `1/1199400791141010:f1d4b85a291da54a88e14813a91d4b97` | Authorization Asana Token |
| `github_token` required | `string` header | `e50d125791d8c9ca25774ab0a758205d74f726ed` | GitHub Token |
| `comply_client_id` | `string` header | `6779ef20e75817b79602` | Client credential generated by comply authentication |
| `comply_client_secret` | `string` header | `269d98e4922fb3895e9ae2108cbb5064` | Client credential generated by comply authentication |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `source_url`required | `string` | URL to project source code. |
| `product_name`required | `string` | Product Name. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `compliance_id` | `string` | Compliance id, used for get compliance status |
##### Other responses
`400``401``403``404`
`GET` `/compliance_metrics`
#### Retrieve Compliance Metrics Generation
`get-compliance-metrics`
Retrieve compliance metrics generation status
Retrieve compliance metrics generation status shows whether compliance metrics are being sent to health product or not.
##### Response
application/json Copy 200 response
```
{
"message": "Sending compliance metrics is enabled."
}
```
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response status |
##### Other responses
`400``401``403``404`
`GET` `/compliance/{compliance_id}`
#### Retrieve Compliance Status
`compliance-status`
Retrieve Compliance Status retrieves the results of the security validation and SOC2 process compliance status such as Change request process performed by Comply for the given compliance_id.
##### Response
200 Succeeded response200 Failed response
application/json Copy 200 response
```
{
"compliance_id": "9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"metadata": {
"service-comply": {
"id": "9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"issuer": "https://api.staircaseapi.com/comply",
"status": "SUCCEEDED",
"severity_label": "LOW",
"timestamp": 1611949487.728646,
"version": "1.0.0"
},
"service-code": {
"commit_hash": "5a8d1bbd276306e73ad5fcb1c45dfe3bb2e6c5c2",
"id": "1506dbf2-ea7b-4b76-9f51-2ebb0ac49af1",
"issuer": "https://api.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1611948276.2954555,
"version": 1.1
}
},
"source_url": "https://code-comply-oybto4.s3.amazonaws.com/comply/devops-code-comply-a51a-56d91d7ed7df/build.zip?AWSAccessKeyId=2525&Signature=TyI1LC0",
"status": "SUCCEEDED",
"warnings": {
"security_violations": [
{
"resource_id": "arn:aws:lambda:us-east-1:791306477523:function:code-assessor-dev-apiGatewayLogHandler",
"resource_type": "AwsLambdaFunction",
"severity": "LOW",
"standar": "PCI-DSS",
"remediation": "https://docs.aws.amazon.com/console/securityhub/PCI.Lambda.2/remediation",
"description": "PCI.Lambda.2 Lambda functions should be in a VPC",
"resource_name": "code-assessor-dev-apigatewayloghandler",
"stack_name": "code-assessor-dev",
"product_name": "Assess"
}
]
}
}
```
application/json Copy 200 response
```
{
"compliance_id": "9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"errors": {
"process_violations": [
{
"process": "Change request process",
"message": "Section Accepted not found"
}
]
},
"metadata": {
"service-comply": {
"id": "9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg",
"issuer": "https://api.staircaseapi.com/comply",
"status": "FAILED",
"severity_label": "HIGH",
"timestamp": 1611949487.728646,
"version": "1.0.0"
},
"service-code": {
"commit_hash": "5a8d1bbd276306e73ad5fcb1c45dfe3bb2e6c5c2",
"id": "1506dbf2-ea7b-4b76-9f51-2ebb0ac49af1",
"issuer": "https://api.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1611948276.2954555,
"version": 1.1
}
},
"status": "FAILED",
"source_url": "https://code-comply-oybto4.s3.amazonaws.com/comply/devops-code-comply-a51a-56d91d7ed7df/build.zip?AWSAccessKeyId=2525&Signature=TyI1LC0",
"warnings": {
"security_violations": [
{
"resource_id": "arn:aws:lambda:us-east-1:791306477523:function:code-assessor-dev-insertRule",
"resource_type": "AwsLambdaFunction",
"severity": "MEDIUM",
"standar": "AWS-Foundational-Security-Best-Practices",
"remediation": "https://docs.aws.amazon.com/console/securityhub/Lambda.4/remediation",
"description": "Lambda.4 Lambda functions should have a dead-letter queue configured",
"resource_name": "code-assessor-dev-insertrule",
"stack_name": "code-assessor-dev",
"product_name": "Assess"
}
]
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `compliance_id` required | `string` path | `9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg` | id of Compliance |
##### Response `200``application/json`
6 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `compliance_id` | `string` | Compliance id |
| `errors` | `object` | Compliance errors |
| `security_violations` | `object` | Contains security violations |
| `source_url` | `string` | Presigned URL metadata in the header for Comply and other products. This metadata is in use as a signature of successful compliance. |
| `status` | `string` | Status of compliance`COMPLIANT``FAILED``FAULT``IN_PROGRESS``NON_COMPLIANT``STOPPED``SUCCEEDED``TIMED_OUT` |
| `metadata` | `object` | Compliance metadata plus metadata included in the compliance presigned URL coming from other products |
| `service-comply` | `object` | Compliance metadata |
| `id` | `string` | Compliance id |
| `issuer` | `string` | Compliance issuer |
| `status` | `string` | Compliance status`COMPLIANT``FAILED``FAULT``IN_PROGRESS``NON_COMPLIANT``STOPPED``SUCCEEDED``TIMED_OUT` |
| `severity_label` | `string` | Compliance severity label`CRITICAL``HIGH``INFORMATIONAL``LOW``MEDIUM` |
| `timestamp` | `object` | Compliance timestamp |
| `version` | `object` | Compliance version |
| `warnings` | `object` | Compliance warnings |
| `process_violations` | `object` | Compliance process violations |
##### Other responses
`400``401``403``404`
`PUT` `/compliance_metrics`
#### Set Compliance Metrics Generation
`put-compliance-metrics`
Set compliance metrics generation
Set compliance metrics generation enables or disables the generation of compliance metrics sent to the health API.
##### Request
Disabling reportEnabling report
application/json Copy
```
{
"compliance_metrics_enabled": "false"
}
```
application/json Copy
```
{
"compliance_metrics_enabled": "true"
}
```
##### Response
application/json Copy 200 response
```
{
"message": "Sending compliance metrics is enabled."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `compliance_metrics_enabled`required | `string` | Compliance metrics generation status |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response status |
##### Other responses
`400``401``403``404`
### Identity
`GET` `/configurations`
#### Retrieve configuration data
`get-configuration-data`
Retrieve configuration data retrieves data to configure an identity provider
##### Response
application/json Copy 200 response
```
{
"acs_url": "https://staircase.com/saml2/idpresponse",
"identity_id": "urn:amazon:cognito:sp:us-east-1_bAcc5ljlp",
"login_url": "https://staircase.com/login?client_id=1236&response_type=token&scope=email+openid&redirect_uri=https://staircase.com/callback"
}
```
##### Response `200``application/json`
3 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `acs_url` | `string` | ACS URL |
| `identity_id` | `string` | Identity id |
| `login_url` | `string` | Login URL |
##### Other responses
`400``401``403``404`
`POST` `/identity_providers`
#### Set identity provider
`set-identity-provider`
Set identity provider Sets identity data using provider metadata**
##### Request
application/json Copy
```
{
"metadata": "Metadata"
}
```
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `metadata`required | `string` | Provider Metadata |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status process |
##### Other responses
`400``401``403``404`
`DELETE` `/identity_providers`
#### Remove identity provider
`remove-identity-provider`
Remove identity provider deletes identity provider settings
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `123` | Authorization Token |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status process |
##### Other responses
`400``401``403``404`
`POST` `/users_access`
#### Set user access
`set-user-access`
Set user access Sets temporary access to specific environments**
##### Request
application/json Copy
```
{
"email": "example@staircase.co",
"expiration": 1441,
"environment_domain": "example.com"
}
```
##### Response
application/json Copy 200 response
```
{
"status": "SUCCEEDED"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `123` | Authorization Token |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `email`required | `string` | User email |
| `expiration` | `integer` | Expiration minutes |
| `environment_domain` | `string` | Environment domain |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status process |
##### Other responses
`400``401``403``404`
### SOC2
`POST` `/soc2/offboarding`
#### Create Offboarding Data
`new-soc2-offboarding-data`
Create offboarding data
Comply looks into controls required for SOC2 compliance. One of these controls is around on-boarding and off-boarding. As part of this control, there must be tasks for new employees to onboard and get access to different systems such as GitHub, G Suite. Comply integrates with Rippling HR tool and Asana task management tool to retrieve the list of employees and to make sure that there is an offboarding task for them. This endpoint can be used by auditors to make sure that Staircase is following required SOC2 controls.
Comply returns an offboarding_data_id in the response body. To retrieve the results of the security validation, call Retrieve offboarding Status with the offboarding_data_id.
##### Request
application/json Copy
```
{
"date_from": "2021-12-01",
"admin_name": "Test Name"
}
```
##### Response
application/json Copy 200 response
```
{
"offboarding_data_id": "9dff4dc3-g700-4fc8-a51a-56d91d7ed7df"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `asana_token` required | `string` header | `1/1199400791141010:f1d4b85a291da54a88e14813a91d4b97` | Authorization Asana Token |
| `rippling_token` required | `string` header | `byqVc9P6Woq0gUI01OMovA3o1wzymReZt3rBvwJTHpzaPwhKzW1fU4zzHkPcC3fe` | Authorization rippling Token |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `date_from`required | `string` | Date From. |
| `admin_name` | `string` | User admin name from asana |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `offboarding_data_id` | `string` | Offboarding data id, used for get offboarding data |
##### Other responses
`400``401``403``404`
`GET` `/soc2/offboarding/{offboarding_data_id}`
#### Retrieve Offboarding Data
`get-soc2-offboarding-data`
Get offboarding data
Retrieve offboarding data retrieves the results of SOC2 offboarding process for a given offboarding_data_id.
##### Response
200 Succeeded response200 Failed response
application/json Copy 200 response
```
{
"status": "COMPLIANT",
"offboarding_data_id": "91ae0517-c3b9-4709-9f4c-55cb7ac231cd",
"offboarding_process": {
"offboarding_tasks": [
{
"employee_name": "Employee Name",
"asana_task": "https://app.asana.com/0/252455/252455588"
}
],
"missing_tasks": []
}
}
```
application/json Copy 200 response
```
{
"status": "FAILED",
"offboarding_data_id": "91ae0517-c3b9-4709-9f4c-55cb7ac231cd",
"offboarding_process": [],
"errors": [
{
"message": "rippling_token not authorized"
}
]
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `offboarding_data_id` required | `string` path | `9dff4dc3-f700-4fc8-a51a-56d91d7ed7dg` | Offboarding data id |
##### Response `200``application/json`
4 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `offboarding_data_id` | `string` | Offboarding data id |
| `errors` | `object` | Errors |
| `status` | `string` | Status of compliance`COMPLIANT``FAILED``FAULT``IN_PROGRESS``NON_COMPLIANT``STOPPED``SUCCEEDED``TIMED_OUT` |
| `offboarding_process` | `object` | Offboarding process data |
##### Other responses
`400``401``403``404`
`POST` `/soc2/onboarding`
#### Create Onboarding Data
`new-soc2-onboarding-data`
Create onboarding data
Comply looks into controls required for SOC2 compliance. One of these controls is around on-boarding and off-boarding. As part of this control, there must be tasks for new employees to onboard and get access to different systems such as GitHub, G Suite. Comply integrates with Rippling HR tool and Asana task management tool to retrieve the list of employees and to make sure that there is an onboarding task for them. This endpoint can be used by auditors to make sure that Staircase is following required SOC2 controls.
Comply returns an onboarding_data_id in the response body. To retrieve the results of the security validation, call Retrieve Onboarding Status with the onboarding_data_id.
##### Request
application/json Copy
```
{
"date_from": "2021-12-01"
}
```
##### Response
application/json Copy 200 response
```
{
"onboarding_data_id": "9dfg4dc3-f700-4fc8-a51a-56d91d7ed7df"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `asana_token` required | `string` header | `1/1199400791141010:f1d4b85a291da54a88e14813a91d4b97` | Authorization Asana Token |
| `rippling_token` required | `string` header | `byqVc9P6Woq0gUI01OMovA3o1wzymReZt3rBvwJTHpzaPwhKzW1fU4zzHkPcC3fe` | Authorization rippling Token |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `date_from`required | `string` | Date From. |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `onboarding_data_id` | `string` | Onboarding data id, used for get onboarding data |
##### Other responses
`400``401``403``404`
`GET` `/soc2/onboarding/{onboarding_data_id}`
#### Retrieve Onboarding Data
`get-soc2-onboarding-data`
Get onboarding data
Retrieve onboarding data retrieves the results of SOC2 onboarding process for a given onboarding_data_id.
##### Response
200 Succeeded response200 Failed response
application/json Copy 200 response
```
{
"status": "COMPLIANT",
"onboarding_data_id": "91ae0517-c3b9-4709-9f4c-55cb7ac231cd",
"onboarding_process": {
"onboarding_tasks": [
{
"employee_name": "Employee Name",
"asana_task": "https://app.asana.com/0/252455/252455588"
}
],
"missing_tasks": []
}
}
```
application/json Copy 200 response
```
{
"status": "FAILED",
"onboarding_data_id": "91ae0517-c3b9-4709-9f4c-55cb7ac231cd",
"onboarding_process": [],
"errors": [
{
"message": "rippling_token not authorized"
}
]
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `onboarding_data_id` required | `string` path | `9dff4dc3-g700-4fc8-a51a-56d91d7ed7df` | Onboarding data id |
##### Response `200``application/json`
4 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `onboarding_data_id` | `string` | Onboarding data id |
| `errors` | `object` | Errors |
| `status` | `string` | Status of compliance`COMPLIANT``FAILED``FAULT``IN_PROGRESS``NON_COMPLIANT``STOPPED``SUCCEEDED``TIMED_OUT` |
| `onboarding_process` | `object` | Onboarding process data |
##### Other responses
`400``401``403``404`
### Machine to Machine
`DELETE` `/app_client/{product_name}`
#### Delete app client
`delete-app-client`
Delete app client Delete app client for product, To be able to use this API you must have "admin" or "product_engineer" profile
##### Response
application/json Copy 200 response
```
{
"message": "SUCCEEDED"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` path | `Test` | Product Name |
| `Authorization` required | `string` header | `123` | Authorization Token |
##### Response `200``application/json`
1 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status process |
##### Other responses
`400``401``403``404`
`GET` `/app_client/{product_name}`
#### Get app client
`get-app-client`
Get app client Get app client for product, To be able to use this API you must have "admin" or "product_engineer" profile
##### Response
application/json Copy 200 response
```
{
"client_id": "client-id",
"client_secret": ""
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` path | `Test` | Product Name |
| `Authorization` required | `string` header | `123` | Authorization Token |
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `client_id` | `string` | Client id |
| `client_secret` | `string` | Client secret |
##### Other responses
`400``401``403``404`
`POST` `/app_client/{product_name}`
#### Create app client
`create-app-client`
Create app client Create new app client for product**, To be able to use this API you must have "admin" or "product_engineer" profile
##### Response
application/json Copy 200 response
```
{
"client_id": "client-id",
"client_secret": ""
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` path | `Test` | Product Name |
| `Authorization` required | `string` header | `123` | Authorization Token |
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `client_id` | `string` | Client id |
| `client_secret` | `string` | Client secret |
##### Other responses
`400``401``403``404`
`POST` `/oauth/validate`
#### Validate access token
`validate-access-token`
Validate access token Validate access token**
##### Response
application/json Copy 200 response
```
{
"sub": "08b02444-76cf-4644-a058-3e5b623f2620",
"identities": "[{\"userId\":\"user@domain.com\",\"providerName\":\"Staircase\",\"providerType\":\"SAML\",\"issuer\":\"https://accounts.google.com/o/saml2?idpid=XXXX22222\",\"primary\":true,\"dateCreated\":1631219658425}]",
"email_verified": "false",
"profile": "developer",
"email": "user@domain.com",
"custom:environments_access": "[]",
"username": "Staircase_user@domain.com"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `Authorization` required | `string` header | `` | Access Token |
##### Other responses
`200``400``401``403``404`
## Providers
- MeridianLink
## Errors
`400``401``403``404``422`
## More in Shipping
- Previous product: Code
- Next product: Deploy
---
# Deploy
# Deploy
Deploying any bundle to any environment, with retry, skip-if-unchanged, and completion reported to the health surface.
A deployment takes a bundle and an environment. It retries on transient failure, cancels cleanly when the platform's code-storage limit is reached rather than half-deploying, and skips entirely when the commit already deployed there.
Completion reports to Health, so the record of what is where is a consequence of deploying rather than a separate bookkeeping step.
## How it works
The skip is keyed on the commit rather than on a version string. A version can be re-tagged; a commit cannot, so the check answers the actual question — is this exact code already running here.
## Operations
### Foo
`POST` `/hello-world`
#### Bar
`helloWorld`
Hello World
Dummy hello world endpoint
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | FooExample `Hello, World!` |
### Deployments
`POST` `/deployments`
#### Deploy Artifact
`deployArtifact`
#### Deploy Artifact
Deploy Artifact deploys a product or configuration artifact_url to a specific environment using only environment token from Environment product to provide information about the environment which is the final target of the deployment.
##### Limitations on Deployment
- Deployment which handled by lambda worker supports up to 3 GB artifact size.
- Deployment retries deployment up to 5 times if Deployer receives service error or throttling error.
- Deployer will cancel deployment if lambda code storage hit %99 percent. The code storage percentage cache TTL is 10 minutes.
##### Legacy deployment
- By default, the Deploy uses the new deployment strategy via StepFunctions. If you want to use the legacy deployment strategy via CodeBuild, you can enable it by passing `legacy_deploy` as true in the request body.
- The legacy deployment strategy is deprecated and will be removed in the future.
- The legacy deployment strategy is slower than the new deployment strategy.
##### Force Deployment
Deployer skips product deployment based on the following conditions:
Show the rest
- The Last deployment should be successful.
- The last deployment commit SHA should match the current bundle commit SHA. This indicates there is no code change in the given bundle.
Note: This behavior does not apply to configuration bundles. Configuration bundle deployments will be executed on every attempt.
This behavior can be changed by forcing the Deployer to execute deployment with the following options:
1. Updating `service.yml`
```
deployment:
force_deployment: true
```
1. Giving `force_deployment` parameter in the request body.
Note: Parameter in request body overrides `service.yml` configuration. The deployment process will report to the Health after deployment finished or failed. The following health metric parameters will be sent: product_identifier: Taken from product_identifier field in the frontend bundles. Support for other bundles coming soon. product_api_identifier: always `be5bed79-df72-4a56-b77c-5c12d4e21d8e` status: "SUCCEEDED" or "FAILED" The deployment accepts optional parameter for transaction ID. If not provided, the deployment will create the transaction for the deployment.. The deployment process will persist following data into collection: Deployment status, `Failed` or `Succeeded`. Start time and end time of deployment. Bundle type of the deployment. `Service`, `Chat`, `FrontEnd`, `Data`.
Example of the collection:
```
{
"metadata": {
"fuzzy_searchable": false,
"version": 3,
"validation": true,
"serialise_to_graph": true
},
"data": {
"bundles": [
{
"@type": "bundle",
"@id": "bundle_id",
"bundle_type": "Service",
"base_path": "your-base-path",
"has_product": "p_id"
}
],
"products": [
{
"@id": "p_id",
"@type": "product",
"name": "MyProductName"
},
{
"@id": "p_id_2",
"@type": "product",
"name": "Deploy",
"product_identifier": "229c0982-b5fe-4d4c-8f9e-80ad38f5d4b8",
"has_product_api": "product_api_id"
}
],
"deployments": [
{
"deployment_status_type": "Succeeded",
"@type": "deployment",
"@id": "depl_id",
"has_invocation": "inv_id",
"has_bundle": "bundle_id",
"start_time": "2024-05-16T05:41:07.868339-04:00",
"end_time": "2024-05-16T05:41:07.868339-04:00"
}
],
"product_apis": [
{
"@type": "product_api",
"@id": "product_api_id",
"name": "Deployment",
"product_api_identifier": "a1257a35-5261-4293-9747-2e958c56f53c"
}
],
"invocations": [
{
"@type": "invocation",
"invocation_message": "my-deployment-id",
"@id": "inv_id",
"has_product_api": "product_api_id"
}
]
}
}
```
##### Request
FullExampleMinimalExampleParallelDeploymentExample
application/json Copy
```
{
"bundle_id": "e00feb67-f6d7-46e4-95a-52375ece86ef",
"transaction_id": "01HY0C4V3JS796NF9FXWDDNXT4",
"artifacts_url": "https://example.com/artifact.zip",
"environment_token": "rWiaN6NN6l0RPrrmM6he3QABhqCAAAAAAGBkJt205xbT9RPaH4kyB2JcGic4f-8vjZCIU7NZE8hVE2Trw6gqsDm0V7OMqST--jJUM3ri24BvyRYrI2EolmyWWKPNGlpVaA7",
"callback_url": "https://example.com/call-me-back-please"
}
```
application/json Copy
```
{
"artifacts_url": "https://example.com/artifact.zip",
"environment_token": "rWiaN6NN6l0RPrrmM6he3QABhqCAAAAAAGBkJt205xbT9RPaH4kyB2JcGic4f-8vjZCIU7NZE8hVE2Trw6gqsDm0V7OMqST--jJUM3ri24BvyRYrI2EolmyWWKPNGlpVaA7"
}
```
application/json Copy
```
{
"environment_token": "env_token",
"artifacts_url": "https://example.com/artifact.zip",
"callback_url": "https://example.com/call-me-back-please"
}
```
##### Response
200 SuccessfulExample200 SuccessfulParallelDeploymentExample400
application/json Copy Deployment started.
```
{
"deploy_id": "devops-deployer-dev:490f5d55-2ea4-47b5-81cb-38a54a01f2af",
"bundle_id": "e00feb67-f6d7-46e4-95a-52375ece86ef",
"transaction_id": "01HY0C4V3JS796NF9FXWDDNXT4"
}
```
application/json Copy Deployment started.
```
{
"deploy_id": "948d0a4b-f228-4f88-b6be-b62627e1c2fd",
"bundle_id": "1906999e-af6a-41eb-92a4-0f9545abd3b8",
"transaction_id": "01HY0C4V3JS796NF9FXWDDNXT4"
}
```
application/json Copy Parameter validation error
```
{
"artifacts_url": [
"Missing data for required field."
],
"environment_token": [
"Missing data for required field."
]
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. |
##### Request body`application/json`
9 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Valid transaction ID from the Persistence product. |
| `bundle_id` | `string (uuid)` | Any UUID. |
| `environment_token`required | `string` | Token from Environment product. |
| `artifacts_url`required | `string (uri)` | Link to the artifacts zip file. Content of artifacts file described in Artifacts content section. Deployer will download artifacts from artifacts_url, and deploy them.Example `https://example.com/artifact.zip` |
| `callback_url` | `string (uri)` | (Optional) When deployment is done, POST to this API information about deployment. If a transient error is returned from callback deploy will retry 10 times to call callback using exponential back off algorithm. Transient error means either: a timeout, an FTP 5xx response code or an HTTP 5xx response code.Example `https://example.com/call-me-back-please` |
| `log_level` | `string` | Log level, that is used in deployment process. Can be used with \"DEBUG\" value for Deploy product debugging.`DEBUG``INFO`Example `INFO` |
| `force_deployment` | `boolean` | This allows Deployer to force execute deployment.Example `true` |
| `legacy_deploy` | `boolean` | Use legacy deployment strategy via CodeBuild. This option is deprecated and will be removed in the future.Example `false` |
| `configuration` | `object` | This option configures deployment and is only effective when legacy_deploy disabled. |
| `limit_check_on_pre_deployment` | `string` | Enables AWS quota and limit check before deployment.Example `true` |
| `parallel_module_deployment` | `string` | Allows configuring parallel or sequential module deployment. Sequential deployment is important when module deployment order matters. This option is valid only for legacy_deploy deployment disabled.Example `true` |
##### Response `200``application/json`
3 fields
Deployment started.
| Field | Type | Description |
| --- | --- | --- |
| `deploy_id` | `string` | ID of the deployment.Example `devops-deployer-dev:490f5d55-2ea4-47b5-81cb-38a54a01f2af` |
| `bundle_id` | `string (uuid)` | Usually a hash of the commit but can be any UUID. |
| `transaction_id` | `string` | The transaction ID. |
##### Response `400``application/json`
2 fields
Parameter validation error
| Field | Type | Description |
| --- | --- | --- |
| `artifacts_url` | `string[]` | Artifact URL errors |
| `environment_token` | `string[]` | Environment token errors |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
`GET` `/deployments/{bundle_id}`
#### Retrieve Deployment Status
`retrieveDeploymentStatus`
Retrieve Deployment Metadata retrieves metadata generated by the deployment.
- Metadata is available only for deployments that succeed (deploy_status==SUCCEEDED).
- The artifact_url key in the response body contains the URL to the artifact that was deployed. This URL only supports the GET method and is valid for one hour. A new request to this endpoint will provide a new artifact_url.
- The response to a GET request for artifact_url will contain headers describing the artifact metadata. Only header names that start with x-amz-meta-service are considered service metadata.
##### Response
200 SuccessfulDeployment200 FailedDeployment200 ParallelDeployment
application/json Copy 200 response
```
{
"deploy_status": "SUCCEEDED",
"metadata": {
"target_url": "https://sandbox.api.staircaseapi.com/code-assessor/",
"code": {
"id": "4ad1c152-4990-45b4-a2ab-f0d31d1fc303",
"timestamp": 1611753194.053118,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "31e47b3e883cec9c46c435d57c58565e1f73b3a8",
"issuer": "https://deploy.staircaseapi.com/code"
},
"builder": {
"id": "f128507e-21c1-4dd8-b6bc-7bb0d220eeb8",
"timestamp": 1611753314.9771907,
"version": "1.1",
"status": "SUCCEEDED",
"issuer": "https://api.staircaseapi.com/infra-builder"
},
"deployer": {
"id": "032e2794-7aa8-4e3a-912b-605f5c370913",
"timestamp": 1611753374.9128177,
"version": "1.1",
"status": "SUCCEEDED",
"issuer": "https://deploy.staircaseapi.com/infra-deployer/"
}
},
"artifact_url": "https://deployer-dev-artifcatsbucket-1freahxorpmya.s3.amazonaws.com/build_artifacts/00c5f4ab-d3d4-4cd9-bc9d-eefe8b6b1c26/devops-deployer-dev/artifacts.zip?AWSAccessKeyId=&Signature=&Expires=1611832432",
"logs": [
"[Container] 2020/12/14 16:24:03 Waiting for agent ping\n",
"[Container] 2020/12/14 16:24:05 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2020/12/14 16:24:06 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2020/12/14 16:24:06 CODEBUILD_SRC_DIR=/codebuild/output/src405111012/src\n",
"[Container] 2020/12/14 16:24:06 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2020/12/14 16:24:06 No commands found for phase name: install\n",
"[Container] 2020/12/14 16:24:06 Processing environment variables\n",
"[Container] 2020/12/14 16:24:06 Selecting 'python' runtime version '3.8' based on manual selections...\n",
"[Container] 2020/12/14 16:24:06 Running command echo \"Installing Python version 3.8 ...\"\n",
"Installing Python version 3.8 ...\n",
"\n",
"[Container] 2020/12/14 16:24:06 Running command pyenv global $PYTHON_38_VERSION\n",
"\n",
"[Container] 2020/12/14 16:24:07 Moving to directory /codebuild/output/src405111012/src\n",
"[Container] 2020/12/14 16:24:07 Registering with agent\n",
"[Container] 2020/12/14 16:24:07 Phases found in YAML: 2\n",
"[Container] 2020/12/14 16:24:07 INSTALL: 0 commands\n",
"[Container] 2020/12/14 16:24:07 BUILD: 6 commands\n",
"[Container] 2020/12/14 16:24:07 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2020/12/14 16:24:07 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:24:07 Entering phase INSTALL\n",
"[Container] 2020/12/14 16:24:07 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2020/12/14 16:24:07 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:24:07 Entering phase PRE_BUILD\n",
"[Container] 2020/12/14 16:24:07 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2020/12/14 16:24:07 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:24:07 Entering phase BUILD\n",
"[Container] 2020/12/14 16:24:07 Running command curl -sS \"\"$HOST\"infra-deployer/deploy.py\" --output deploy.py\n",
"\n",
"[Container] 2020/12/14 16:24:10 Running command curl -sS $ARTIFACTS_URL --output artifacts.zip\n",
"\n",
"[Container] 2020/12/14 16:24:11 Running command unzip -qq artifacts.zip -d build_folder\n",
"\n",
"[Container] 2020/12/14 16:24:11 Running command printf \"$ACCESS_KEY\\n$SECRET_KEY\\nus-east-1\\njson\" > creds.txt\n",
"\n",
"[Container] 2020/12/14 16:24:11 Running command aws configure < creds.txt\n",
"AWS Access Key ID [None]: AWS Secret Access Key [None]: Default region name [None]: Default output format [None]:\n",
"[Container] 2020/12/14 16:24:16 Running command python3.8 deploy.py build_folder\n",
"2020-12-14 16:24:17,684 Found credentials in shared credentials file: ~/.aws/credentials\n",
"2020-12-14 16:24:18,007 Creating bucket 2b7d31ed-7ff3-4da8-9ad9-324f40bf41a0\n",
"2020-12-14 16:24:18,323 Bucket created\n",
"2020-12-14 16:24:18,324 Uploading artifacts\n",
"2020-12-14 16:24:18,574 Artifacts uploaded\n",
"2020-12-14 16:24:18,574 Deployment started\n",
"2020-12-14 16:25:30,449 Deployed\n",
"2020-12-14 16:25:30,449 Removing bucket 2b7d31ed-7ff3-4da8-9ad9-324f40bf41a0\n",
"2020-12-14 16:25:31,128 Bucket removed\n",
"\n",
"[Container] 2020/12/14 16:25:31 Running command if [ \"$CALLBACK_URL\" != \"null\" ]; then\n",
"\n if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then\n",
"\n curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
"\n else\n",
"\n curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
"\n fi\n",
"fi\n",
"",
"\n % Total % Received % Xferd Average Speed Time Time Time Current\n",
"\n Dload Upload Total Spent Left Speed\n",
"\r 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0\r 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0\r100 75 0 0 100 75 0 247 --:--:-- --:--:-- --:--:-- 246\n",
"\n",
"[Container] 2020/12/14 16:25:31 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2020/12/14 16:25:31 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:25:31 Entering phase POST_BUILD\n",
"[Container] 2020/12/14 16:25:31 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2020/12/14 16:25:31 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:25:31 Expanding base directory path: .\n",
"[Container] 2020/12/14 16:25:31 Assembling file list\n",
"[Container] 2020/12/14 16:25:31 Expanding .\n",
"[Container] 2020/12/14 16:25:31 Expanding file paths for base directory .\n",
"[Container] 2020/12/14 16:25:31 Assembling file list\n",
"[Container] 2020/12/14 16:25:31 Expanding deploy_output.json\n",
"[Container] 2020/12/14 16:25:31 Found 1 file(s)\n",
"[Container] 2020/12/14 16:25:31 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED\n",
"[Container] 2020/12/14 16:25:31 Phase context status code: Message:\n"
]
}
```
application/json Copy 200 response
```
{
"deploy_status": "FAILED",
"metadata": null,
"artifact_url": null,
"logs": [
"[Container] 2020/12/14 16:55:13 Waiting for agent ping\n",
"[Container] 2020/12/14 16:55:15 Waiting for DOWNLOAD_SOURCE\n",
"[Container] 2020/12/14 16:55:16 Phase is DOWNLOAD_SOURCE\n",
"[Container] 2020/12/14 16:55:16 CODEBUILD_SRC_DIR=/codebuild/output/src092437202/src\n",
"[Container] 2020/12/14 16:55:16 YAML location is /codebuild/readonly/buildspec.yml\n",
"[Container] 2020/12/14 16:55:16 No commands found for phase name: install\n",
"[Container] 2020/12/14 16:55:16 Processing environment variables\n",
"[Container] 2020/12/14 16:55:16 Selecting 'python' runtime version '3.8' based on manual selections...\n",
"[Container] 2020/12/14 16:55:16 Running command echo \"Installing Python version 3.8 ...\"\n",
"Installing Python version 3.8 ...\n",
"\n",
"[Container] 2020/12/14 16:55:16 Running command pyenv global $PYTHON_38_VERSION\n",
"\n",
"[Container] 2020/12/14 16:55:16 Moving to directory /codebuild/output/src092437202/src\n",
"[Container] 2020/12/14 16:55:16 Registering with agent\n",
"[Container] 2020/12/14 16:55:16 Phases found in YAML: 2\n",
"[Container] 2020/12/14 16:55:16 INSTALL: 0 commands\n",
"[Container] 2020/12/14 16:55:16 BUILD: 6 commands\n",
"[Container] 2020/12/14 16:55:16 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED\n",
"[Container] 2020/12/14 16:55:16 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:55:16 Entering phase INSTALL\n",
"[Container] 2020/12/14 16:55:16 Phase complete: INSTALL State: SUCCEEDED\n",
"[Container] 2020/12/14 16:55:16 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:55:16 Entering phase PRE_BUILD\n",
"[Container] 2020/12/14 16:55:16 Phase complete: PRE_BUILD State: SUCCEEDED\n",
"[Container] 2020/12/14 16:55:16 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:55:16 Entering phase BUILD\n",
"[Container] 2020/12/14 16:55:16 Running command curl -sS \"\"$HOST\"infra-deployer/deploy.py\" --output deploy.py\n",
"\n",
"[Container] 2020/12/14 16:55:20 Running command curl -sS $ARTIFACTS_URL --output artifacts.zip\n",
"\n",
"[Container] 2020/12/14 16:55:20 Running command unzip -qq artifacts.zip -d build_folder\n",
"[artifacts.zip]\n",
"\n End-of-central-directory signature not found. Either this file is not\n",
"\n a zipfile, or it constitutes one disk of a multi-part archive. In the\n",
"\n latter case the central directory and zipfile comment will be found on\n",
"\n the last disk(s) of this archive.\n",
"unzip: cannot find zipfile directory in one of artifacts.zip or\n",
"\n artifacts.zip.zip, and cannot find artifacts.zip.ZIP, period.\n",
"\n",
"[Container] 2020/12/14 16:55:20 Command did not exit successfully unzip -qq artifacts.zip -d build_folder exit status 9\n",
"[Container] 2020/12/14 16:55:20 Running command if [ \"$CALLBACK_URL\" != \"null\" ]; then\n",
"\n if [ \"$CODEBUILD_BUILD_SUCCEEDING\" = \"1\" ]; then\n",
"\n curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"SUCCEEDED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
"\n else\n",
"\n curl --request POST $CALLBACK_URL --header 'Content-Type: application/json' --data '{\"status\": \"FAILED\",\"bundle_id\": \"'$BUNDLE_ID'\"}'\n",
"\n fi\n",
"fi\n",
"\n",
"[Container] 2020/12/14 16:55:20 Phase complete: BUILD State: FAILED\n",
"[Container] 2020/12/14 16:55:20 Phase context status code: COMMAND_EXECUTION_ERROR Message: Error while executing command: unzip -qq artifacts.zip -d build_folder. Reason: exit status 9\n",
"[Container] 2020/12/14 16:55:20 Entering phase POST_BUILD\n",
"[Container] 2020/12/14 16:55:20 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2020/12/14 16:55:20 Phase context status code: Message:\n",
"[Container] 2020/12/14 16:55:20 Expanding base directory path: .\n",
"[Container] 2020/12/14 16:55:20 Assembling file list\n",
"[Container] 2020/12/14 16:55:20 Expanding .\n",
"[Container] 2020/12/14 16:55:20 Expanding file paths for base directory .\n",
"[Container] 2020/12/14 16:55:20 Assembling file list\n",
"[Container] 2020/12/14 16:55:20 Expanding deploy_output.json\n",
"[Container] 2020/12/14 16:55:20 Skipping invalid file path deploy_output.json\n",
"[Container] 2020/12/14 16:55:20 Phase complete: UPLOAD_ARTIFACTS State: FAILED\n",
"[Container] 2020/12/14 16:55:20 Phase context status code: CLIENT_ERROR Message: no matching artifact paths found\n"
]
}
```
application/json Copy 200 response
```
{
"bundle_id": "225b1744-2b9f-4861-b8b5-55bf4dd0726f",
"deploy_id": "fb27c142-5421-4f51-8a5d-bb5078e6e7c6",
"metadata": {
"assessor": {
"id": "877c9b30-8179-4719-855b-2206984a34e2",
"timestamp": 1653058579.240083,
"version": "1.0.12",
"issuer": "https://template.staircaseapi.com/code-assessor",
"status": "SUCCEEDED",
"applied_rules": 39,
"version_hash": "635c7ac814f451e200f8ce55462a576600767300da6539cf77deaa056397c670"
},
"code": {
"id": "f1321002-9f83-46a7-8eb5-ab8db6f5d197",
"timestamp": 1653058526.3055882,
"version": "1.1",
"status": "SUCCEEDED",
"commit_hash": "d8300821be61e603f549747dd0c44350069f1f9f",
"issuer": "https://template.staircaseapi.com/code"
},
"builder": {
"id": "d126a1d2-b222-4ab7-8880-e66737cbb79d",
"timestamp": 1653058800.9849484,
"version": "1.1",
"status": "SUCCEEDED",
"bundle_type": "SERVICE",
"issuer": "https://template.staircaseapi.com/infra-builder"
},
"deployer": {
"id": "fb27c142-5421-4f51-8a5d-bb5078e6e7c6",
"timestamp": 1653059651.2567577,
"version": "1.1",
"status": "SUCCEEDED",
"issuer": "https://template.staircaseapi.com/infra-deployer/"
}
},
"deploy_status": "SUCCEEDED",
"bundle_details": [
{
"created_at": "2022-05-20:15:14:14",
"status": "SUCCEEDED",
"finished_at": "2022-05-20:15:14:33",
"stack_id": "arn:aws:cloudformation:us-east-1:111122222:stack/deployer-dev/4d607ab0-69f3-11eb-99cd-0ae749a35905",
"cf_status": "UPDATE_COMPLETE",
"bundle_id": "225b1744-2b9f-4861-b8b5-55bf4dd0726f"
},
{
"created_at": "2022-05-20:15:13:53",
"deploy_id": "fb27c142-5421-4f51-8a5d-bb5078e6e7c6",
"status": "REQUEST_MADE",
"stack_id": "root",
"callback_url": "callback_url",
"bundle_id": "225b1744-2b9f-4861-b8b5-55bf4dd0726f"
}
]
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. |
| `bundle_id` required | `string (uuid)` path | `e00feb67-f6d7-46e4-95a-52375ece86ef` | Usually a hash of the commit but can be any UUID. |
##### Response `200``application/json`
5 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `deploy_status` | `string` | Deploy status can be SUCCEEDED'|'FAILED'|'FAULT'|'TIMED_OUT'|'IN_PROGRESS'|'STOPPED.`FAILED``FAULT``IN_PROGRESS``STOPPED``SUCCEEDED``TIMED_OUT` |
| `metadata` | `object` | Metadata |
| `target_url` | `string (uri)` | Target URLExample `https://sandbox.api.staircaseapi.com/code-assessor/` |
| `artifact_url` | `string (uri)` | URL of deployed artifact, with proper metadata in headers. |
| `logs` | `string[]` | Logs of deployment. |
| `bundle_details` | `object[]` | Bundle deployment details |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `409``application/json`
1 fields
Request could not be processed because of conflict in the current state of the resource
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`400``422`
`GET` `/deployments/logs/{response_collection_id}`
#### Retrieve Deployment Logs
`retrieveDeploymentLogs`
Retrieve Deployment Logs retrieves logs and stack traces if an exception occurred during deployment. This endpoint is reachable with an API key and health key.
#### Limitations:
- Logs have 7 days TTL.
##### Response
application/json Copy 200 response
```
[
{
"response_collection_id": "225b1744-2b9f-4861-b8b5-55bf4dd0726f",
"product_api_identifier": "11225b1744-239f-4861-b8b5-55bf4dd072",
"transaction_id": "fb27c142-5421-4f51-8a5d-bb5078e6e7c6",
"stack_trace": "stack_trace_value",
"created_at": "2022-12-01:07:23:07",
"expire_at": 1670484187
}
]
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. |
| `response_collection_id` required | `string (uuid)` path | `e00feb67-f6d7-46e4-95a-52375ece86ef` | The value of response collection_id. |
| `product_api_identifier` | `string` query | `11225b1744-239f-4861-b8b5-55bf4dd072` | Product API identifier |
##### Response `200``application/json`
6 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `response_collection_id` | `string` | Response collection identifier. |
| `product_api_identifier` | `string` | Product API identifier. |
| `transaction_id` | `string` | Transaction identifier |
| `stack_trace` | `string` | Execution stack trace |
| `created_at` | `string` | Log creation date. |
| `expire_at` | `number` | Log expiration specifier. |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `409``application/json`
1 fields
Request could not be processed because of conflict in the current state of the resource
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`400``422`
### Operations
`GET` `/deployments/{deployId}`
#### Get deploy status
`Getdeploy`
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `deployId` required | `string` path | ID of deploy, looks like 5f0631cd1487f8000897e143 |
##### Other responses
`200`
`POST` `/deploymentStrategies/blue-green/execute`
#### Redeploy
`Redeploy`
##### Request
application/json Copy
```
{
"applicationName": "app",
"oldDeployId": "5efb0e03b61e2500082c8292",
"revisionLocation": "s3://staircase-poc/GreenDeploy_Linux.zip"
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `applicationName`required | `string` | — |
| `oldDeployId`required | `string` | — |
| `revisionLocation`required | `string` | — |
##### Other responses
`200`
## Errors
`400``403``404``409``422`
## More in Shipping
- Previous product: Comply
- Next product: Health
---
# Health
# Health
Per-transaction metrics, cost metrics, and a per-partner performance report carrying vendor success rate and cost.
Every invocation reports timing, outcome and cost. The surface serves that back as transaction metrics, cost metrics, custom report templates, and the public status view.
The per-partner report carries success rate and cost per vendor, which is the measurement a waterfall ordering is retuned from — the ordering is only as good as the evidence that a vendor is answering.
## How it works
Vendor performance was reported from the beginning rather than added once someone asked. That is the difference between a waterfall as an idea and a waterfall that can be tuned: without per-vendor success and cost, the order is a guess that nobody can correct.
## Operations
### Status
`POST` `/`
#### Update status
`updateHealthStatus`
Update product status
##### Request
application/json Copy
```
{
"product_id": "test_product",
"product_api_id": "test_api",
"environment_fqdn": "test_env.example.com",
"available": true
}
```
##### Response
200400
application/json Copy Successfully updated product status
```
{
"product_id": "test_product",
"status": "operational"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string` | Product ID |
| `status`required | `string` | Status |
##### Response `200``application/json`
2 fields
Successfully updated product status
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string` | Category |
| `status`required | `string` | Status`major_outage``operational``partial_outage` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/{product_id}`
#### Retrieve status
`getHealthStatus`
Get product status
Get product availability status
##### Response
200400404
application/json Copy Successfully fetched product status
```
{
"product_id": "test_product",
"status": "operational"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string` path | `01GYWNA8PJX5A41WA48PZNV5Y4` | Product ID |
##### Response `200``application/json`
2 fields
Successfully fetched product status
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string` | Category |
| `status`required | `string` | Status`major_outage``operational``partial_outage` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Metric Alarm Events
`GET` `/alarms/events`
#### List Metric Alarm Events
`list_metric_alarm_events`
This service returns a list of occurred alarm events. NOTE: Alarm events have one week retention period. Events that passed the retention period will be deleted.
##### Response
200400 error response400 text/html404
application/json Copy Ok.
```
{
"events": [
{
"expire_at": 1663939815,
"event_id": "2f9e3499-8e5d-4003-b524-ed23aca2ac38",
"metric_data": {
"transaction_id": "01GD37M86FM1AZ2QXQ243NDKHE",
"product_identifier": "c72b3b7c-dc30-41d0-81d3-3d3889370ef2",
"product_api_identifier": "77958f4b-7158-42d0-adbd-22e2b74fe0c9",
"invocation_code": "2000",
"elapsed_time": 147.4666051864624,
"created_at": "2022-09-16 09:30:13",
"response_collection_id": "d4f48c0f-6560-4da9-8c8d-a54d10d22d7e",
"id": "37e9b907-ef5b-4e54-b782-de1e64259a80",
"configuration_id": "e1b96c6d-d24e-459c-ae8a-ec460df3de8f",
"product_build_hash": "f144ef21958ba7cde95a9bbd5372ec99605af106",
"host_environment": "health.staircaseapi.com",
"status": "SUCCEEDED"
},
"created_at": "2022-09-16T09:30:13",
"alarm_id": "alarm_id_1"
}
],
"next_token": null
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
7
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `alarm_id` required | `string` query | `product_identifier_1` | Alarm ID |
| `start_date` required | `string` query | `2022-01-01T00:00:00` | Start date in ISO format |
| `end_date` required | `string` query | `2022-01-01T01:01:01` | End date in ISO format |
| `next_token` | `string` query | `eyJwcm9kdWN0X25hbWUiOiAiQnVpbGQiLCAiY3JlYXRlZF9hdCI6ICIyMDIxLTA2LTA0VDE0OjU5OjE5LjU3MTg3OSJ9` | The token for the next set of items to return. |
| `limit` | `string` query | `150` | The number of results to return in this request |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `events` | `object[]` | List of events |
| `alarm_id` | `string` | Alarm IDExample `alarm_id_1` |
| `event_id` | `string` | Event IDExample `event_id_1` |
| `created_at` | `string` | Event creation date.Example `2022-09-16T09:30:13` |
| `expire_at` | `integer` | Event item expiration timestamp.Example `1663939815` |
| `metric_data` | `object` | Metric payload |
| `id` | `string` | Metric IDExample `37e9b907-ef5b-4e54-b782-de1e64259a80` |
| `host_environment` | `string` | Metric host environmentExample `health.staircaseapi.com` |
| `product_identifier` | `string` | Product IdentifierExample `c72b3b7c-dc30-41d0-81d3-3d3889370ef2` |
| `product_api_identifier` | `string` | Product API identifierExample `77958f4b-7158-42d0-adbd-22e2b74fe0c9` |
| `transaction_id` | `string` | Transaction IDExample `01GD37M86FM1AZ2QXQ243NDKHE` |
| `response_collection_id` | `string` | Response collection IDExample `d4f48c0f-6560-4da9-8c8d-a54d10d22d7e` |
| `elapsed_time` | `number` | Elapsed timeExample `147.46` |
| `status` | `string` | StatusExample `SUCCEEDED` |
| `invocation_code` | `string` | Invocation codeExample `2000` |
| `configuration_id` | `string` | Product configuration IDExample `e1b96c6d-d24e-459c-ae8a-ec460df3de8f` |
| `product_build_hash` | `string` | Product build hashExample `f144ef21958ba7cde95a9bbd5372ec99605af106` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Metric Alarms
`POST` `/alarms/metric`
#### Create Metric Alarm
`create_metric_alarms`
#### Metric Alarm
Health alarms provide real-time alerts based on a given condition. If you want to be notified when an alert event has occurred, you can select a destination option. You are able to select one or more destination channels from the available options.
##### Condition
Health alarms are generated based on given conditions.
##### Destinations
Notification can be delivered after the alert event has occurred. Destinations are notification channels for alert delivery. One or more notification channels can be selected ex: Slack, and Webhook.
- Slack: Slack integration requires a slack token that belongs to Slack apps. Please create a new application by using Slack API. After application creation, go to channel configuration and add created Slack app as an integration using "Apps" section in the "Integrations" tab.
##### Request
Create Metric AlarmAlarm Only If campaign_id is present in metric
application/json Copy
```
{
"alarm_id": "alarm_id_1",
"condition": {
"product_identifier": "product_identifier_1",
"product_api_identifiers": [
"product_api_identifier_1"
]
},
"destinations": [
{
"type": "SLACK",
"slack_channel": "slack_channel_1",
"slack_token": "slack_token_1",
"slack_usergroup_id": "S03TW2A7A3U"
},
{
"type": "WEBHOOK",
"url": "https://webhook.com"
}
]
}
```
application/json Copy
```
{
"alarm_id": "alarm_id_1",
"condition": {
"product_identifier": "product_identifier_1",
"required_properties": [
"campaign_id"
]
},
"destinations": [
{
"type": "SLACK",
"slack_channel": "slack_channel_1",
"slack_token": "slack_token_1",
"slack_usergroup_id": "S03TW2A7A3U"
},
{
"type": "WEBHOOK",
"url": "https://webhook.com"
}
]
}
```
##### Response
201400 application/json400 text/html404
application/json Copy Success response.
```
{
"message": "migration configuration created"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `alarm_id`required | `string` | Unique alarm ID |
| `condition`required | `object` | Alarm filter configuration |
| `host_environment` | `string` | Host environment |
| `product_identifier`required | `string` | Product identifier |
| `product_api_identifiers` | `string[]` | List of product api identifiers |
| `configuration_ids` | `string[]` | List of product configuration ID |
| `statuses` | `string[]` | List of status |
| `invocation_codes` | `string[]` | List of invocation codes |
| `product_build_hash` | `string` | Product build hash |
| `elapsed_time_above` | `number` | Filters metrics which has elapsed time above |
| `elapsed_time_below` | `number` | Filters metrics which has elapsed time below |
| `required_properties` | `string[]` | List of required properties |
| `destinations`required | `array` | List of alarm destinations |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`PUT` `/alarms/metric/{alarm_id}`
#### Update Metric Alarm
`update_metric_alarm`
This service updates metric alarm.
##### Request
application/json Copy
```
{
"condition": {
"product_identifier": "product_identifier_1",
"product_api_identifiers": [
"product_api_identifier_1"
]
},
"destinations": [
{
"type": "SLACK",
"slack_channel": "slack_channel_1",
"slack_token": "slack_token_1"
},
{
"type": "WEBHOOK",
"url": "https://webhook.com"
}
]
}
```
##### Response
201400 application/json400 text/html404
application/json Copy Success response.
```
{
"message": "migration configuration updated"
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `x-api-key` required | `string` header | `` | API key |
| `alarm_id` required | `string` path | `alarm_id_1` | Unique alarm ID |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `condition`required | `object` | Alarm filter configuration |
| `host_environment` | `string` | Host environment |
| `product_identifier`required | `string` | Product identifier |
| `product_api_identifiers` | `string[]` | List of product api identifiers |
| `statuses` | `string[]` | List of status |
| `invocation_codes` | `string[]` | List of invocation codes |
| `configuration_ids` | `string[]` | List of product configuration ID |
| `product_build_hash` | `string` | Product build hash |
| `elapsed_time_above` | `number` | Filters metrics which has elapsed time above |
| `elapsed_time_below` | `number` | Filters metrics which has elapsed time below |
| `slack_usergroup_id` | `string` | Slack usergroup id. Use this to tag your team group in the slack message. This ID ALWAYS starts with S and is followed by 9 characters.Example `slack_usergroup_id_1` |
| `required_properties` | `string[]` | List of required properties |
| `destinations`required | `array` | List of alarm destinations |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`GET` `/alarms/metric`
#### List Metric Alarms
`list_metric_alarms`
This service returns list of metric alarms.
##### Response
200400 error response400 text/html404
application/json Copy Ok.
```
{
"alarms": [
{
"destinations": [
{
"type": "SLACK",
"slack_channel": "slack_channel_1",
"slack_token": "slack_token_1"
}
],
"alarm_id": "alarm_id_1",
"condition": {
"product_api_identifiers": [
"product_api_identifier_1"
],
"product_identifier": "product_identifier_1"
}
}
]
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `product_identifier` | `string` query | `product_identifier_1` | Filters by product identifier |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `alarms` | `object[]` | Configurations |
| `alarm_id` | `string` | Unique configuration name. Value can be alphanumeric and underscore characters only.Example `test_configuration` |
| `condition` | `object` | Target environment API key |
| `host_environment` | `string` | Host environmentExample `health.staircaseapi.com` |
| `product_identifier` | `string` | Product identifierExample `ccd6b8dd-02a7-4c64-a983-7e0c108cd666` |
| `product_api_identifiers` | `array` | List of api identifiers |
| `statuses` | `array` | List of status |
| `invocation_codes` | `array` | List of invocation codes |
| `configuration_ids` | `array` | List of configuration ID |
| `product_build_hash` | `string` | Product build hash |
| `elapsed_time_above` | `number` | Elapsed time above filterExample `5` |
| `elapsed_time_below` | `number` | Elapsed time below filterExample `10` |
| `destinations` | `array` | List of alarm destinations |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`GET` `/alarms/metric/{alarm_id}`
#### Get Metric Alarm
`get_metric_alarms`
This service returns metric alarms.
##### Response
200400 error response400 text/html404
application/json Copy Ok.
```
{
"destinations": [
{
"type": "SLACK",
"slack_channel": "slack_channel_1",
"slack_token": "slack_token_1"
}
],
"alarm_id": "alarm_id_1",
"condition": {
"product_api_identifiers": [
"product_api_identifier_1"
],
"product_identifier": "product_identifier_1"
}
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `x-api-key` required | `string` header | `` | API key |
| `alarm_id` required | `string` path | `alarm_id_1` | Unique alarm ID |
##### Response `200``application/json`
3 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `alarm_id` | `string` | Unique configuration name. Value can be alphanumeric and underscore characters only.Example `test_configuration` |
| `condition` | `object` | Target environment API key |
| `host_environment` | `string` | Host environmentExample `health.staircaseapi.com` |
| `product_identifier` | `string` | Product identifierExample `ccd6b8dd-02a7-4c64-a983-7e0c108cd666` |
| `product_api_identifiers` | `array` | List of api identifiers |
| `statuses` | `array` | List of status |
| `invocation_codes` | `array` | List of invocation codes |
| `configuration_ids` | `array` | List of configuration ID |
| `product_build_hash` | `string` | Product build hash |
| `elapsed_time_above` | `number` | Elapsed time above filterExample `5` |
| `elapsed_time_below` | `number` | Elapsed time below filterExample `10` |
| `destinations` | `array` | List of alarm destinations |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`DELETE` `/alarms/metric/{alarm_id}`
#### Delete Metric Alarm
`delete_metric_alarm`
This service deletes metric alarm.
##### Response
200400 error response400 text/html404
application/json Copy Ok.
```
{
"message": "migration configuration deleted"
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `x-api-key` required | `string` header | `` | API key |
| `alarm_id` required | `string` path | `alarm_id_1` | Unique alarm ID |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unique configuration nameExample `test_configuration` |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Custom Reports
`POST` `/build-report`
#### Create Custom Report
`create_custom_report`
Build a custom report using the metrics posted for any product or custom-created metric types.
Build a custom report using the metrics posted for any product or custom-created metric types. Define the fields to retrieve, the filters to apply, and the aggregation if needed.
The report data to retrieve can be defined in two ways:
- Aggregated:Providing the aggregation function, aggregation_fields and group_by will allow to bring the results aggregated.
- Detailed:Specify the fields and filters to retrieve detailed metrics data.
##### Request
Examples - Detailed reportExample - Aggregated
application/json Copy
```
{
"get": [
"product_name",
"status",
"transaction_id",
"request_collection_id",
"response_collection_id",
"operation_status",
"partner_name",
"severity",
"service_endpoint"
],
"filters": {
"product_name": [
"Health",
"Account"
],
"status": [
"succeeded"
],
"host_env": [
"health.staircaseapi.com"
]
},
"report_name": "report_to_create_name",
"metric_type": "performance"
}
```
application/json Copy
```
{
"get": [
"product_name",
"service_endpoint",
"status"
],
"filters": {
"product_name": [
"Health"
]
},
"aggregation": "count",
"aggregation_field": "transaction_id",
"group_by": [
"product_name",
"service_endpoint",
"status"
],
"report_name": "report_to_create_name",
"metric_type": "performance"
}
```
##### Response
201400 0400 text/html403502
application/json Copy Success Response
```
{
"message": "the custom report was successfully created"
}
```
application/json Copy Bad request error
```
{
"message": "Error in metric_type creation: the Report simples2 already exists"
}
```
text/html Copy Bad request error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Error.
```
{
"message": "Internal server error"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `get` | `string[]` | Items which will be retrieved (product_name, status, transaction_id,request_collection_id,response_collection_id,operation_status,partner_name,severity,service_endpoint,created_at) |
| `metric_type` | `string` | The name of the metric type created or use "performance" for transaction and logging metrics posted in the Health. |
| `aggregation` | `string` | For aggregated reports, it will calculate the given function (count, avg, sum) |
| `aggregation_field` | `string` | For aggregated reports, it will calculate the aggregation function with this field. Example(transaction_id, response_collection_id) |
| `group_by` | `array` | For aggregated reports, it will group the data by these fields. Example(product_name, service_endpoint) |
| `filters` | `object` | Filters applied for the report |
| `environment` | `string[]` | Environment example |
| `product_name` | `string[]` | Product Name Example |
| `status` | `string[]` | Status Example |
| `report_name` | `string` | Name of the Report. |
##### Response `201``application/json`
1 fields
Success Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Bad request error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `502``application/json`
1 fields
Error.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message error |
`GET` `/get-report`
#### Retrieve Custom Report
`get_custom_report`
This service runs a custom report and allows to retrieve the results for the given report structure.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
See the service Update custom report to change the structure of the report.
##### Response
200400 0400 text/html403
application/json Copy Success
```
{
"Items": [
{
"product_name": "Assess",
"status": "succeeded",
"transaction_id": "1ce37c58-12aa-400f-a7b6-97f5d63b0e50",
"host_env": "health.staircaseapi.com",
"created_at": "2021-06-25 14:03:03.504"
}
]
}
```
application/json Copy Error Response
```
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
```
text/html Copy Error Response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `report_name` required | `string` query | `simples221` | The name of the Report |
| `start_date` required | `string` query | `2021-01-01` | Start date |
| `end_date` required | `string` query | `2021-06-30` | End date |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `Items` | `object[]` | Items |
| `transaction_id` | `string` | Field name |
| `created_at` | `string` | Field name |
| `host_env` | `string` | Field name |
| `product_name` | `string` | Field name |
| `status` | `string` | Field name |
##### Response `400``application/json`
1 fields
Error Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`PUT` `/update-build-report`
#### Update Custom Report
`update_custom_report`
This service allows updating a custom report structure.
This service allows updating a custom report structure.
##### Request
Examples - Detailed reportExample - Aggregated
application/json Copy
```
{
"get": [
"product_name",
"status",
"transaction_id",
"request_collection_id",
"response_collection_id",
"operation_status",
"partner_name",
"severity",
"service_endpoint"
],
"filters": {
"product_name": [
"Health",
"Account"
],
"status": [
"succeeded"
],
"environment": [
"health.staircaseapi.com"
]
},
"report_name": "report_to_create_name",
"metric_type": "performance"
}
```
application/json Copy
```
{
"get": [
"product_name",
"service_endpoint",
"status"
],
"filters": {
"product_name": [
"Health"
]
},
"aggregation": "count",
"aggregation_field": "transaction_id",
"group_by": [
"product_name",
"service_endpoint",
"status"
],
"report_name": "report_to_create_name",
"metric_type": "performance"
}
```
##### Response
200400403502
application/json Copy Success Response
```
{
"message": "the custom report was successfully updated"
}
```
application/json Copy 400 Bad Request
```
{
"message": "Error in updating report: the Report report_to_create_name does not exist"
}
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Error.
```
{
"message": "Internal server error"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `get` | `string[]` | Items which will be retrieved (product_name, status, transaction_id,request_collection_id,response_collection_id,operation_status,partner_name,severity,service_endpoint,created_at) |
| `metric_type` | `string` | The name of the metric type created or use "performance" for transaction and logging metrics posted in the Health. |
| `filters` | `object` | Filters applied for the report |
| `environment` | `string[]` | Environment example |
| `product_name` | `string[]` | Product Name Example |
| `status` | `string[]` | Status Example |
| `report_name` | `string` | Name of the Report. |
##### Response `200``application/json`
1 fields
Success Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
400 Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `502``application/json`
1 fields
Error.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message error |
`GET` `/get-report-id`
#### Retrieve Custom Report Id
`get_custom_report_id`
This service runs a custom report and allows to retrieve the results for the given report structure.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
The response will be a report id which could be used to retrieve the report using the service /get-report-result See the service Update custom report to change the structure of the report.
##### Response
200400 0400 text/html403
application/json Copy Success
```
{
"report_id": "4e6a5826-9a18-4656-b527-03dd7ad1b258",
"Items": []
}
```
application/json Copy Error Response
```
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
```
text/html Copy Error Response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `report_name` required | `string` query | `simples221` | The name of the Report |
| `start_date` required | `string` query | `2021-01-01` | Start date |
| `end_date` required | `string` query | `2021-06-30` | End date |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Response `200``application/json`
2 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `report_id` | `string` | Field name |
| `Items` | `array` | Items |
##### Response `400``application/json`
1 fields
Error Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`GET` `/get-report-result`
#### Retrieve Custom Report CSV
`get_custom_report_results_csv`
This service runs a custom report and allows to retrieve the results as a pre signed URL which contains a CSV file with the report results.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
See the service Update custom report to change the structure of the report.
##### Response
200400 0400 text/html403
application/json Copy Success
```
{
"Items": [
{
"product_name": "Assess",
"status": "succeeded",
"transaction_id": "1ce37c58-12aa-400f-a7b6-97f5d63b0e50",
"host_env": "health.staircaseapi.com",
"created_at": "2021-06-25 14:03:03.504"
}
]
}
```
application/json Copy Error Response
```
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
```
text/html Copy Error Response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `report_id` required | `string` query | `simples221` | The id of the report |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Response `200``application/json`
1 fields
Success
| Field | Type | Description |
| --- | --- | --- |
| `Items` | `object[]` | Items |
| `transaction_id` | `string` | Field name |
| `created_at` | `string` | Field name |
| `host_env` | `string` | Field name |
| `product_name` | `string` | Field name |
| `status` | `string` | Field name |
##### Response `400``application/json`
1 fields
Error Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
### Cost Metrics
`POST` `/cost-metric`
#### Create a Cost Metric
`create_cost_metric`
Create a cost metric. These metrics are used to track customer costs.
##### Request
Example Cost metricExample Cost Mortgage
application/json Copy
```
{
"product_name": "Health",
"transaction_id": "3041fe98-4005-438d-9e14-5849ed8d6cc6",
"cost_in_cents": 95,
"cost_category": "customer"
}
```
application/json Copy
```
{
"product_name": "Data Extraction",
"transaction_id": "1234",
"cost_in_cents": 25,
"partner": "softworks",
"document_type": "W2",
"request_collection_id": "01FH8712A4W0TDKGQQ5QF9B8S",
"response_collection_id": "01FHAZNF0E0070QSKYS6DW62EH",
"pages": "1",
"cost_category": "partner"
}
```
##### Response
201400 application/json400 text/html403
application/json Copy Success response.
```
{
"message": "cost metric created"
}
```
application/json Copy Error Response.
```
{
"message": "error in store cost metric"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key |
##### Request body`application/json`
9 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
| `cost_in_cents`required | `number` | The Cost in cents. It must be an integer number. |
| `pages` | `string` | The number of pages of a document used for data extraction. |
| `partner` | `string` | Partner |
| `product_name`required | `string` | The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment. |
| `document_type` | `string` | The type of document in the data extraction. Example: W2cost: the cost price. |
| `cost_category`required | `string` | There are only two types of cost_category allowed (partner and customer)Example `customer` |
| `request_collection_id` | `string (string)` | A request collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
| `response_collection_id` | `string (string)` | A response collection in Staircase is a container for the elements that a product has as an output for its execution.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
##### Response `201``application/json`
1 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message response |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`GET` `/cost-metric`
#### Retrieve a Cost Metric
`get_cost_metric`
Retrieve a list of cost metric. These metrics are used to track customer costs.
##### Response
200400 error response400 text/html403
application/json Copy Ok.
```
{
"cost_metrics": [
{
"product_name": "Health",
"transaction_id": "2345678a",
"cost_in_cents": "123",
"partner": "test-partner",
"document_type": "test-1",
"pages": "223",
"created_at": "2021-10-04 15:06:06.720"
},
{
"product_name": "Health",
"transaction_id": "2345678a",
"cost_in_cents": "162",
"partner": "test-partner",
"document_type": "test-1",
"pages": "223",
"created_at": "2021-10-04 15:06:13.462"
}
]
}
```
application/json Copy Error response example
```
{
"Error": "Invalid Parameter document"
}
```
text/html Copy Error response example
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
11
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` | `string` query | `2345678a` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
| `product_name` | `string` query | `Health` | The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment. |
| `partner` | `string` query | `softworks` | Partner |
| `cost_in_cents` | `string` query | `95` | Cost |
| `pages` | `string` query | `110` | The number of pages of a document used for data extraction. |
| `cost_category` | `string` query | `partner` | Cost category the metric belongs to. |
| `document_type` | `string` query | `test-1` | The type of document in the data extraction. |
| `start_date` | `string` query | `2021-04-13` | If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` | `string` query | `2021-04-16` | If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `date` | `string` query | `2021-04-16` | If provided, filters by date Date must be in ISO8601 format: YYYY-MM-DD |
| `x-api-key` required | `string` header | `` | API key |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `Items` | `object[]` | Items |
| `transaction_id` | `string` | Transaction Identifier |
| `cost_in_cents` | `string` | cost |
| `pages` | `string` | pages |
| `partner` | `string` | partner |
| `created_at` | `string` | Creation date in timestamp format |
| `product_name` | `string` | Name of the Product |
| `document_type` | `string` | Type of the document |
##### Response `400``application/json`
1 fields
Error response example
| Field | Type | Description |
| --- | --- | --- |
| `Error` | `string` | Error |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
### Development
`POST` `/development-products`
#### Mark as development env for specific product
`register_env`
Mark this environment as development env for specific product, so failures for this product on this env will not affect Staircase status page.
##### Request
application/json Copy
```
{
"product_id": "ccd6b8dd-02a7-4c64-a983-7e0c108cd666",
"is_disabled": true
}
```
##### Response
text/html Copy 400 response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string` | The product id that we want to mark as development env.Example `ccd6b8dd-02a7-4c64-a983-7e0c108cd666` |
| `is_disabled`required | `boolean` | If true, disable sending alerts for this product_id on this env.Example `true` |
##### Response `201``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The environment was configured successfully |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error in storing the environment invalid host |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Performance Metrics
`POST` `/metric/{transaction_id}`
#### Create New Metric
`create_metric`
Create New Metric.
Registers a metric identified by a transaction_id or a unique identifier to track product performance, If multiple services in a product perform processing for the same transaction, the services should send their results to Create New Metric, enabling customers to see the result for one transaction between all products.
Create New Metric tracks the following metric types:
- Transaction: For every service endpoint invocation, a metric of this type is posted to Health providing information about the service, error, or relevant data to track.
Show the rest
- Logging: For every service endpoint invocation the logging metrics are posted to follow up the execution process in the source code and including relevant information to track an issue.
Health Metrics stores additional fields depending on the product family that allows tracking product KPIs.
Single Health Metric payload has 256 KB size limit.
Creating a new metric programmatically example:
```
import requests
from uuid import uuid4
import json
import boto3
client = boto3.client('dynamodb')
def create_metric(event, **kwargs):
transaction_id = str(uuid4)
request_host = event["headers"]["Host"]
service_url = request_host + event['path']
x_api_key = event['headers']['x-api-key']
logging_message = kwargs["logging_message"] if "logging_message" in kwargs else None
if "error" in kwargs and isinstance(kwargs['error'], dict):
payload = {
"host_environment": request_host,
"product_name": kwargs['product_name'],
"metric_type": kwargs['metric_type'],
"logging_message": logging_message,
"method": kwargs['method'],
"service_endpoint": service_url,
"error": kwargs['error'],
"data":
{ "status": kwargs['status_response']}
}
else:
payload = {
"host_environment": request_host,
"product_name": kwargs['product_name'],
"metric_type": kwargs['metric_type'],
"logging_message": logging_message,
"method": kwargs['method'],
"service_endpoint": service_url,
"data":
{ "status": kwargs['status_response']}
}
requests.post(
f"",
headers={"x-api-key": x_api_key},
json=payload
)
@cors_headers
def lambda_handler(event, context):
try:
# Example doing something
create_metric(event, product_name="test_example", metric_type="logging", "logging_message"="start handler" method="POST", status_response=200 )
item_example = {
"Enterprise": "Staircase",
"Phone":"1-347-563-5689",
}
response = client.put_item(
TableName='string',
Item=item_example
)
# Example create a successfully metric
create_metric(event, product_name="test_example", metric_type="transaction", method="POST", status_response=200 )
# return function example
return {
'statusCode': 200,
'body': json.dumps({'response': response })
}
except Exception as e:
# create metric error
create_metric(event, product_name="test_example", error={
"status": 400,
"message": 'error',
"code": 42042}, metric_type="transaction", method="POST", status_response=200 )
# return function example
return {
'statusCode': 400,
'body': json.dumps({'response': e })
}
```
##### Request
MortgagePlatformDevops and other productsExample error metricExample logging metricExample failed logging metric
application/json Copy Use HealthMetricInputV3 schema - An example of error report.
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "employment",
"service_endpoint": "/employment",
"method": "POST",
"metric_type": "transaction",
"partner_name": "truework",
"operation_status": "STARTED",
"request_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27
}
```
application/json Copy Use HealthMetricInputV3 schema
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "Connector",
"service_endpoint": "/vendors/{vendor_name}/flows/{flow_name}/jobs",
"method": "POST",
"metric_type": "transaction",
"partner_name": "truework",
"request_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27
}
```
application/json Copy Use HealthMetricInputV3 schema -
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "Code",
"service_endpoint": "/clone",
"method": "POST",
"metric_type": "transaction",
"operation_status": "IN PROGRESS",
"data": {
"project": "Health",
"branch": "main"
}
}
```
application/json Copy Use HealthMetricInputV3 schema - An example of error report.
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "Code",
"service_endpoint": "/clone",
"method": "POST",
"metric_type": "transaction",
"error": {
"status": 500,
"code": 42042,
"message": "Internal server error",
"more_info": "https://httpstatuses.com/500"
},
"data": {
"project": "Health",
"branch": "main"
}
}
```
application/json Copy Example using metric as logging in metric_type.
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "Code",
"service_endpoint": "/clone",
"method": "POST",
"metric_type": "logging",
"logging_message": "Connect to Github",
"elapsed_time": 200.27,
"data": {
"project": "Health",
"branch": "main"
}
}
```
application/json Copy Example using metric as logging in metric_type.
```
{
"host_environment": "documentation.staircaseapi.com",
"product_name": "Code",
"service_endpoint": "/clone",
"method": "POST",
"metric_type": "logging",
"logging_message": "Connect to Github",
"data": {
"project": "Health",
"branch": "main"
},
"error": {
"status": 500,
"code": 42042,
"message": "Internal server error"
}
}
```
##### Response
201400 application/json400 text/html403500
application/json Copy Ok.
```
{
"message": "metrics created."
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Failed Creation.
```
{
"message": "Internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `transaction_id` required | `string` path | `3cd0ffab-6e87-40a8-bc84-697155131f4c` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
##### Request body`application/json`
14 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `string` | The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.Example `employment` |
| `host_environment` | `string` | Environment host where the product is deployed.Example `documentation.staircaseapi.com` |
| `service_endpoint`required | `string` | The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product.Example `/metric/%7Btransaction_id%7D` |
| `method` | `string` | HTTP's method or verb that indicates the service endpoint operation type.`DELETE GET PATCH POST PUT`Example `POST` |
| `metric_type` | `string (string)` | The type of metric to create, valid options: logging | transaction`logging``transaction`Example `logging` |
| `logging_message` | `string (string)` | This field is only available for logging metric_type. It is used for logging purpose.Example `Get collection translation` |
| `data` | `object` | Receives a valid JSON with data fields the product wants to log to track issues faster. |
| `request_collection_id` | `string (string)` | A request collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
| `response_collection_id` | `string (string)` | A response collection in Staircase is a container for the elements that a product has as an output for its execution.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
| `partner_name` | `string` | The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field.Example `Atomic` |
| `severity` | `string` | The type of the severity to create metric.`CRITICAL``DEBUG``ERROR``HIGH``INFO``LOW``MEDIUM``WARNING` |
| `operation_status` | `string` | Every single Staircase service endpoint (such as POST /persistence/transactions or POST /aus/underwrite) is required to provide operation status updates to denote the progress of a transaction in its execution. For more information see the Health overview page with examples.`ABORTED``CANCELLED``COMPLETED``CREATED``EMAIL_CONFIRMED``ERROR``FAILED``IN PROGRESS``IN_PROGRESS``NOT_FOUND``REQUEST_MADE``RUNNING``STARTED``SUCCEEDED``SUCCEEDED_WITH_WARNING``TIMED_OUT``TIMEOUT``UNAUTHORIZED``WAITING_FOR_RESPONSE`Example `COMPLETED` |
| `elapsed_time` | `number` | The measured duration of an event. The time is expressed in seconds.Example `120.27` |
| `error` | `object` | Receives a valid JSON with the fields to store the error or exception details that occurred during the operation execution. The metric is considered as failed when the error details are provided |
| `status`required | `integer` | Status or error code that will be returned by the serviceExample `401` |
| `code` | `integer` | Internal error codes.Example `42042` |
| `message`required | `string` | Message of Status Code.Example `Unauthorized` |
| `more_info` | `string` | Additional Information on ErrorExample `https://api.staircase.co/docs/errors/42042` |
##### Response `201``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message the metric was successfully created |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message error |
`GET` `/metric`
#### Retrieve Metrics
`transactions_list`
The service retrieves a list of metrics given one or multiple filters. To retrieve all results, send the request with the same query parameters and next_token provided on the previous call until next_token does not appear in the response.
The parameters must use URL Encoding for Special Characters ``` e.g. Left Curly Brace (“{”) = “%7B”, Right Curly Brace (“}”) = “%7D” ``` service_endpoint=%7Btransaction_id%7D
Example: service_endpoint=/metric/%7Btransaction_id%7D, for the service "/metric/%7Btransaction_id%7D"
##### Response
200400 application/json400 text/html403
application/json Copy Ok.
```
{
"Success response": {
"value": {
"next_token": "eyJwcm9kdWN0X25hbWUiOiAiQnVpbGQiLCAiY3JlYXRlZF9hdCI6ICIyMDIxLTA2LTA0VDE0OjU5OjE5LjU3MTg3OSJ9",
"metrics": [
{
"created_at": "2021-07-07T14:17:28.991666-04:00",
"product_name": "a",
"status": "succeeded",
"customer_api_key": "f5c4fec5-2159-4ca4-a061-ab8938ceb70d",
"transaction_id": "11111111111111",
"service_endpoint": "/bulg",
"elapsed_time": "120.0",
"service_name": "a"
},
{
"request_collection_id": "a",
"created_at": "2021-05-13T14:07:36.598931-04:00",
"product_name": "aa",
"status": "succeeded",
"transaction_id": "KLKLKLKLKLKLKLKLKLKLKLKL",
"service_endpoint": "",
"service_name": "aa"
}
]
}
}
}
```
application/json Copy Error Response.
```
{
"response": {
"value": {
"message": "Filters not allowed ",
"allowed filters": [
"product_name",
"status",
"partner_name",
"metric_type",
"operation_stauts",
"product_name and severity",
"product_name and status",
"operation_stauts and partner_name",
"start_date and end_date can be combined with every filter"
]
}
}
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
15
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `service_name` | `string` query | `/employment` | It will be consider as product_name, If provided, filters by concrete product name. |
| `product_name` | `string` query | `employment` | If provided, filters by concrete product name. |
| `criterion` | `string` query | `succeeded` | It will be consider status. Available values: failed, succeeded |
| `status` | `string` query | `succeeded` | status. Available values: failed, succeeded |
| `partner_name` | `string` query | `Atomic` | If provided, filters by partner_name |
| `operation_status` | `string` query | `STARTED` | If provided, filters by operation_status |
| `metric_type` | `string` query | `logging` | If provided, filters by metric_type |
| `severity` | `string` query | `LOW` | If provided, filters by severity |
| `start_date` | `string` query | `2021-04-13` | If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` | `string` query | `2021-04-16` | If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `date` | `string` query | `2021-04-16` | If provided, filters by date Date must be in ISO8601 format: YYYY-MM-DD |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `customer_api_key` | `string` query | `954913e2-db71-4f22-b71c-ef803915eb2b` | It is the key required in order to use the API. Filters by customer_api_key. |
| `elapsed_time` | `string` query | `120.27` | The measured duration of an event. The time is expressed in seconds. |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `next_token` | `string` | Pagination Token |
| `metrics` | `object[]` | Metrics |
| `host_environment` | `string` | Environment host where the product is deployed. |
| `service_endpoint` | `string` | The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product. |
| `product_name` | `string` | The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment. |
| `created_at` | `string` | A collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document. |
| `operation_status` | `string` | The status of an operation given the nature of the actions performed by the service and the transaction result. The service endpoint operation could be successful but the transaction_id could have different status given certain conditions and other operations performed. |
| `metric_type` | `string` | The type of metric options allowed logging | transaction |
| `logging_message` | `string` | This field is only available for metric_type equals logging. It is used for logging purpose. |
| `transaction_id` | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
| `severity` | `string` | Severity e.g. (HIGH, MEDIUM, LOW)`CRITICAL``DEBUG``ERROR``HIGH``INFO``LOW``MEDIUM``WARNING` |
| `customer_api_key` | `string` | It is the key required in order to use the API. Filters by customer_api_key. |
| `partner_name` | `string` | The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field. |
| `elapsed_time` | `string` | The measured duration of an event. The time is expressed in seconds. |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`GET` `/metric/{transaction_id}`
#### Retrieve Metrics by Transaction ID
`get_metrics`
Retrieve Metrics by transaction_id
Retrieve all health reports for specified transaction_id
##### Response
200400 application/json400 text/html403500
application/json Copy Ok.
```
{
"Success Response": {
"metrics": [
{
"host_environment": "health.staircaseapi.com",
"created_at": "2021-07-02T14:52:18.657665-04:00",
"product_name": "Health",
"data": {
"request_data": "9384b4ac-9ea5-4926-824c-eefe37d9689c"
},
"status": "succeeded",
"customer_api_key": "954913e2-db71-4f22-b71c-ef803915eb2b",
"transaction_id": "9384b4ac-9ea5-4926-824c-eefe37d9689c",
"metric_type": "transaction",
"method": "GET",
"service_endpoint": "/metric"
}
]
}
}
```
application/json Copy Error Response.
```
{
"message": "Error in metric retrieving"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Error while retrieving metrics.
```
{
"message": "Internal server error"
}
```
##### Parameters
8
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
| `transaction_id` required | `string (uuid)` path | `3cd0ffab-6e87-40a8-bc84-697155131f4c` | An Identifier for a Transaction in Staircase. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `product_name` | `string` query | `Code` | filters by concrete product name. |
| `host_environment` | `string` query | `health.staircaseapi.com` | filters by host environment. |
| `status` | `string` query | `succeeded` | filters by status. Available values: failed, succeeded |
| `service_endpoint` | `string` query | `/transactions` | filters by service endpoint |
| `method` | `string` query | `GET` | filters by Http Methods. Available values DELETE GET PATCH POST PUT |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `metrics` | `object[]` | Response Body |
| `host_environment` | `string` | Environment host where the product is deployed. |
| `service_endpoint` | `string` | The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product. |
| `product_name` | `string` | The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment. |
| `metric_type` | `string` | The type of metric options allowed logging | transaction |
| `logging_message` | `string` | This field is only available for metric_type logging. It is used for logging purpose. |
| `created_at` | `string` | A collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document. |
| `operation_status` | `string` | The status of an operation given the nature of the actions performed by the service and the transaction result. The service endpoint operation could be successful but the transaction_id could have different status given certain conditions and other operations performed. |
| `transaction_id` | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
| `severity` | `string` | Severity e.g. (HIGH, MEDIUM, LOW)`CRITICAL``DEBUG``ERROR``HIGH``INFO``LOW``MEDIUM``WARNING` |
| `customer_api_key` | `string` | It is the key required in order to use the API. Filters by customer_api_key. |
| `partner_name` | `string` | The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field. |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Error while retrieving metrics.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response Body |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Health Metrics
`POST` `/metrics`
#### Create Health Metric
`create_health_metric`
Create New Health Metric.
#### Health Metric
##### Product Identifier
A product is an entity in the ontology. Product identifiers can be retrieved from Marketplace after product registration. Please visit Marketplace for product registration.
##### Product Api Identifier
API can be referenced by unique ID under products. Please visit Marketplace for API registration.
##### Transaction ID
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
Show the rest
##### Response Collection ID
A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies an execution.
##### Status
| Status | Description |
| --- | --- |
| REQUEST_MADE | Request received successful by API. |
| IN_PROGRESS | Invocation has not reached a final state. |
| SUCCEEDED | Invocation finished successfully. |
| FAILED | Invocation was not successful. |
##### Elapsed Time
Amount of time that passes between the beginning of the request and the end of the invocation.
##### Invocation Code
The invocation code provides information for the invocation response. Codes and descriptions are given below. Please raise CR if needed invocation code is not listed here.
| Invocation Code | Description |
| --- | --- |
| 2000 | OK. Invocation is successful |
| 4000 | BAD_REQUEST. The server cannot or will not process the request due to something that is perceived to be a client error. |
| 4001 | UNAUTHORIZED. The client is not authenticated to get the requested response. |
| 4003 | FORBIDDEN. The client is known but has no access rights to the content. |
| 4004 | NOT_FOUND. The server can not find the requested resource. |
| 4009 | CONFLICT. The request could not be completed due to a conflict with the current state of the target resource. |
| 4013 | PAYLOAD_TOO_LARGE. The request entity is larger than the limits defined by the server. |
| 4022 | UNPROCESSABLE_ENTITY. The request was well-formed but was unable to be followed due to semantic errors. |
| 4029 | TOO_MANY_REQUEST. The user has sent too many requests in a given amount of time. |
| 5000 | INTERNAL_SERVER_ERROR. The server has encountered a situation it does not know how to handle. |
| 5004 | TIMEOUT. This error response is given when the server cannot get a response in time. |
| 6000 | PARTNER_CALL_SUCCESS. Partner invocation returns a successful response. |
| 6001 | PARTNER_CALL_ERROR_INVALID_AUTH. Unauthorized partner call. |
| 6002 | PARTNER_CALL_ERROR_TIMEOUT. The partner did give the response in the given time. |
| 6003 | PARTNER_CALL_ERROR_TOO_MANY_REQUESTS. Partner called too many times in the amount of time that partner defined. |
| 6004 | PARTNER_CALL_ERROR_INVALID_PAYLOAD. Provided payload to the partner is invalid. |
| 6005 | PARTNER_CALL_ERROR_SERVICE_ERROR. Partner returns generic/unclassified service error. |
| 6006 | PARTNER_CALL_ERROR_NOT_FOUND The server cannot find the requested resource. |
| 6007 | PARTNER_CALL_ERROR_CONFLICT This response is sent when a request conflicts with the current state of the server. |
| 7000 | COLD_START. The server received the request successfully but had an initialization process before working on the client request. |
| 7001 | INTERNAL_OPERATION_THRESHOLD_EXCEEDED. The server could not finish the internal operation at the given threshold. The threshold can be duration, coverage, etc. |
| 7002 | INTERNAL_OPERATION_FAILED. The server completed transaction but had failure in the internal operation. |
| 7003 | OVERHEAD. Metric for measuring overhead on given service. |
| 8000 | SITE_SESSION_INITIATED. Metric for measuring Site Sessions. |
| 8001 | SITE_PAGE_CHANGED. Metric for measuring Site page changes. |
| 8002 | CONSOLE_APP_LOADED. Metric for measuring Console App loads. |
| 8003 | CONSOLE_APP_USED_DATA. Metric for calculating if Console App used prepopulated data. |
| 9001 | EMAIL_SEND. Email send. The send request was successful and the email provider will attempt to deliver the message to the recipient’s mail server. |
| 9002 | EMAIL_DELIVERY. Email delivery. The email provider successfully delivered the email to the recipient’s mail server. |
| 9003 | EMAIL_OPEN. Email open. The recipient received the message and opened it in their email client. |
| 9004 | EMAIL_CLICK. The recipient clicked one or more links in the email. |
| 9400 | EMAIL_DELIVERY_DELAY. The email couldn’t be delivered to the recipient’s mail server because a temporary issue occurred. |
| 9401 | EMAIL_UNSUBSCRIBE. The email was successfully delivered, but the recipient updated their subscription preferences by clicking on an unsubscribe link. |
| 9403 | EMAIL_COMPLAINT. The email was successfully delivered to the recipient’s mail server, but the recipient marked it as spam. |
| 9500 | EMAIL_REJECT. The email provider accepted the email but determined that it contained a virus and didn’t attempt to deliver it to the recipient’s mail server. |
| 9501 | EMAIL_BOUNCE. The recipient’s mail server permanently rejected the email. |
| 9502 | EMAIL_RENDERING_FAILURE. The email wasn’t sent because of a template rendering issue. |
##### Product Build Hash
The builder generates a hash value after every product build. The hash value indicates which build version the metric comes from. Please check Builder documentation for details and how to get the build hash.
##### Request
application/json Copy An example health metric.
```
{
"product_identifier": "ccd6b8dd-02a7-4c64-a983-7e0c108cd666",
"product_api_identifier": "1236b8dd-02a7-4c64-a983-7e0c108cd666",
"transaction_id": "01F2Q6WJXF5DK3ERTZ18JHSNE8",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"invocation_code": "6001",
"status": "FAILED",
"elapsed_time": 200.27
}
```
##### Response
201400 application/json400 text/html
application/json Copy Ok.
```
{
"id": "86a9ef39-5907-4fb6-bdc5-987017b6c999",
"message": "metrics created."
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `x-sc-trace-id` | `string` header | `041fe98-4005-438d-9e14-5849ed8d6cc6` | Id to trace all transactions related. It will be generated automatically if not provided. |
##### Request body`application/json`
20 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_identifier`required | `string` | Unique product identifier.Example `ccd6b8dd-02a7-4c64-a983-7e0c108cd666` |
| `product_api_identifier`required | `string` | Unique product api identifierExample `548070b4-6ea7-459e-9746-5020446b3a73` |
| `transaction_id`required | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `3cd0ffa-6e87-40a8-bc84-697155131f4c` |
| `response_collection_id`required | `string (string)` | A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
| `status`required | `string` | Indicates status of the process.`FAILED``IN_PROGRESS``REQUEST_MADE``SUCCEEDED`Example `SUCCEEDED` |
| `elapsed_time`required | `number` | The measured duration of an event. The time is expressed in seconds.Example `120.27` |
| `invocation_code`required | `string` | Product invocation response code. For more information please check invocation code mapping.Example `6001` |
| `configuration_id` | `string` | Product configuration ID. |
| `product_build_hash` | `string` | Hash value that generated from builder. |
| `campaign_id` | `string` | Campaign ID |
| `user_agent` | `string` | Optional. Represents actor's user agent. This will not be derived from the request headers if omitted.Example `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3` |
| `person_guid` | `string` | Person GUID |
| `phone_call_callback_number` | `string` | Callback number |
| `virtual_phone_number` | `string` | To phone number |
| `communication_identifier` | `string` | From phone number |
| `call_center_number` | `string` | Call center number |
| `lead_identifier` | `string` | Lead identifier |
| `voice_transcription` | `string` | The text representation of the spoken audio, transcribed from voice input. |
| `sms_text` | `string` | The SMS text that we received. |
| `x-sc-trace-id` | `string` | Id to trace all transactions related. It will be generated automatically if not provided. |
##### Response `201``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique metric id. |
| `message` | `string` | Message the metric was successfully created |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`POST` `/metrics/query`
#### Create Asynchronous Health Metric Query
`create_async_health_query_execution`
Create Asynchronous Health Query Execution
#### Query Execution
Create Asynchronous Health Metric Query creates and executes the query immediately, for the query status and results invoke Get Asynchronous Health Metric Query Result. If you invoke multiple times Get Asynchronous Health Metric Query Result for the same query_id you will receive the same results set that was created during the (first) execution. Each execution of Create Asynchronous Health Metric Query creates a new query and result set.
#### Limits
| Limit | Value |
| --- | --- |
| Concurrent Query Execution | 20 query execution per second |
#### Timezone
The Health product uses the timezone Eastern Standard Time (UTC-5). Please specify the `include_timezone` field in the query configuration to get time with timezone information included.
##### Request
Query BodyQuery Body List Fields
application/json Copy Create asynchronous query execution
```
{
"transaction_id": "01F2Q6WJXF5DK3ERTZ18JHSNE8",
"start_date": "2022-04-11T00:00:00",
"end_date": "2022-04-11T23:59:59"
}
```
application/json Copy Create asynchronous query execution
```
{
"start_date": "2022-04-11T00:00:00",
"end_date": "2022-04-11T23:59:59",
"product_identifier": "ccd6b8dd-02a7-4c64-a983-7e0c108cd666",
"invocation_codes": [
7000,
7001
]
}
```
##### Response
201400 application/json400 text/html
application/json Copy Ok.
```
{
"query_id": "c62a1228-fae7-44c8-aebe-8706ecfb9fc4",
"status": "PENDING"
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
22 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_identifier` | `one of` | Product identifier |
| `product_api_identifier` | `one of` | Product api identifier |
| `transaction_id` | `one of` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled. |
| `response_collection_id` | `one of` | A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution. |
| `invocation_code` | `one of` | Code that indicates invocation response |
| `status` | `one of` | Indicates status of the process. |
| `configuration_id` | `one of` | Product configuration ID. |
| `product_build_hash` | `one of` | Hash value that generated from builder. |
| `campaign_id` | `one of` | campaign_id from metric body. |
| `user_agent` | `one of` | user_agent from metric body. |
| `person_guid` | `one of` | person_guid from metric body. |
| `phone_call_callback_number` | `one of` | callback number from metric body. |
| `virtual_phone_number` | `one of` | virtual_phone_number number from metric body. |
| `call_center_number` | `one of` | call_center_number number from metric body. |
| `lead_identifier` | `one of` | lead_identifier from metric body. |
| `communication_identifier` | `one of` | phone number from metric body. |
| `voice_transcription` | `one of` | The text representation of the spoken audio, transcribed from voice input. |
| `query_configuration` | `object` | Query configuration |
| `include_timezone` | `boolean` | Includes timezone info and update date format to ISO8601. |
| `include_host_environment` | `boolean` | Includes environment domain info to result set. |
| `callback_url` | `string (uri)` | When query execution is done, this url will be called with resultExample `https://webhook.com/callback` |
| `start_date`required | `string` | Datetime must be in ISO8601 format.Example `2021-08-13T00:00:00` |
| `end_date`required | `string` | Datetime must be in ISO8601 format. Should be later than `start_date`Example `2021-08-13T23:59:59` |
| `x-sc-trace-id` | `string` | Id to trace all transactions related.Example `041fe98-4005-438d-9e14-5849ed8d6cc6` |
##### Response `201``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `query_id` | `string` | Unique identifier for running query execution |
| `status` | `string` | Status of the query execution |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`GET` `/metrics/query/{query_id}`
#### Get Asynchronous Health Metric Query Result
`get_async_health_query_result`
The service retrieves a list of metrics by given query id. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.
##### Response
200400 application/json400 text/html404
application/json Copy Ok.
```
{
"status": "SUCCEEDED",
"result_csv_file": "https://athena-query-results-293107503335.s3.amazonaws.com/1cf6527c-95cc-4998-b273-d3f4b9dd8014.csv&Expires=1661502173",
"next_token": "QVdzd01lM0VwNUNSUjNjakRRMllkNDBEdi92ZWZ6ODJXNFBGZnAxMmk4QjhlcTUrQ2tVaTFIZGpOSXRyYThUYU9YRHVHRzlzN3cxMXEwZTUzY3ZETGxOVHZQOWkwSFYzTUE9PQ==",
"metrics": [
{
"created_at": "2022-08-26 02:34:46",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-1",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:34:49",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-2",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:34:52",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-3",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:34:55",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-4",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:34:58",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-5",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:35:02",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-6",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:35:05",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-7",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:35:08",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-8",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
},
{
"created_at": "2022-08-26 02:35:12",
"host_environment": "health.staircaseapi.com",
"product_identifier": "product_identifier_1",
"product_api_identifier": "product_api_identifier_1",
"transaction_id": "test-9",
"response_collection_id": "01F2Q6WJXF5DK3ERTZ1E9NDNE8",
"elapsed_time": 200.27,
"status": "IN_PROGRESS",
"invocation_code": "2000"
}
]
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `query_id` required | `string` path | `1fc23e2-b13e-405a-a3de-a5228950e3b8` | Unique query execution id |
| `x-api-key` required | `string` header | `` | API key |
| `limit` | `integer` query | `150` | The number of results to return in this request. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `query_id` required | `string` path | `query_id_1` | Query ID received previously with asynchronous query creation |
##### Response `200``application/json`
4 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the query execution`FAILED``IN_PROGRESS``SUCCEEDED`Example `SUCCEEDED` |
| `result_csv_file` | `string` | Url for query result in CSV formatExample `https://athena-query-results-293107503335.s3.amazonaws.com/1cf6527c-95cc-4998-b273-d3f4b9dd8014.csv?%2Fol&Expires=1661502173` |
| `next_token` | `string` | Indicates next page exist. Using this token next page can retrieve.Example `QVdMejZQT0gzY1I5ZmZCOXF2V1NlQW1Za2xITTNRYWtiVFViRUswYUVScWk2ZFJ3Q0xRRFFaQkx0QXVNVlU3K0JvZU8yTDIzc0RCSGNlcGg0TE5ZdExIeWJNeDlidDBSNkE9PQ==` |
| `metrics` | `object[]` | Metrics |
| `id` | `string` | Metric unique identifierExample `babb5fb4-b587-4914-a84c-c52c431b7905` |
| `created_at` | `string` | Metric creation date.Example `2022-08-26 02:34:46` |
| `host_environment` | `string` | Environment host where the product is deployed.Example `health.staircaseapi.com` |
| `product_identifier` | `string` | Unique product identifier.Example `ccd6b8dd-02a7-4c64-a983-7e0c108cd666` |
| `product_api_identifier` | `string` | Unique product api identifier.Example `548070b4-6ea7-459e-9746-5020446b3a73` |
| `transaction_id` | `string` | Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example `3cd0ffa-6e87-40a8-bc84-697155131f4c` |
| `response_collection_id` | `string` | A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution.Example `01F2MHXNNNVK02YEY63Q5EQ59T` |
| `elapsed_time` | `number` | The measured duration of an event. The time is expressed in seconds.Example `14.55` |
| `status` | `string` | Indicates status of the process.Example `IN_PROGRESS` |
| `invocation_code` | `string` | Product invocation response code.Example `2000` |
| `configuration_id` | `string` | Product configuration ID.Example `e1b96c6d-d24e-459c-ae8a-ec460df3de8f` |
| `product_build_hash` | `string` | Product build hash.Example `46b5218a58aed835e63a3b7bf158742600dfbf10` |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Aggregation[new]
`POST` `/metrics/aggregation/query`
#### Aggregate Health Metrics[new]
`aggregate_health_metrics`
Aggregate Health Metrics
The service creates aggregated metric query execution for the given query parameters.
#### Aggregation
##### Date
If specified, fillers data between the given start and end date and group them according to the given date interval.
###### Interval
Allowed interval types:
- `second`
- `minute`
- `hour`
- `day`
##### Filters
Multiple filters that applied before grouping metrics. Filter condition applied according to the given operator onto the given field.
Show the rest
| Allowed Operator | Allowed Field |
| --- | --- |
| `=` | `product_identifier`, `product_api_identifier`, `transaction_id`, `response_collection_id` , `status`, `invocation_code`, `configuration_id`, `product_build_hash` |
##### Group By
Group values with a given field. Allowed field names:
- `product_identifier`
- `product_api_identifier`
- `transaction_id`
- `response_collection_id`
- `status`
- `invocation_code`
- `configuration_id`
- `product_build_hash`
##### Methods
Allows applying methods on filtered and grouped results. Methods are defined and applicable according to filed names. `row` is a special keyword for representing a single row in the result set.
| Allowed Method | Allowed field |
| --- | --- |
| `COUNT` | `row`, `product_identifier`, `product_api_identifier`, `transaction_id`, `response_collection_id` , `status`, `invocation_code`, `elapsed_time`, `configuration_id`, `product_build_hash` |
| `SUM` | `elapsed_time` |
| `AVG` | `elapsed_time` |
| `P50, P90, P95, P99` | `elapsed_time` |
##### Limits
| Limit | Value |
| --- | --- |
| Concurrent Aggregation Execution | 20 query execution per second |
##### Request
Product APIs Hourly Status Distribution Product APIs Hourly Avg Elapsed times
application/json Copy Create asynchronous query execution
```
{
"date": {
"start_date": "2022-10-03T00:00:00",
"end_date": "2022-10-10T23:59:59",
"interval": {
"type": "hour",
"value": "1"
}
},
"filters": [
{
"field_name": "product_identifier",
"field_value": "e53e749f-38ec-4435-943f-6d5c6d32bc12",
"operator": "="
}
],
"group_by": [
"product_identifier",
"product_api_identifier",
"status"
],
"methods": [
{
"method_name": "COUNT",
"field_name": "row"
}
]
}
```
application/json Copy Create asynchronous query execution
```
{
"date": {
"start_date": "2022-10-03T00:00:00",
"end_date": "2022-10-10T23:59:59",
"interval": {
"type": "hour",
"value": "1"
}
},
"filters": [
{
"field_name": "product_identifier",
"field_value": "e53e749f-38ec-4435-943f-6d5c6d32bc12",
"operator": "="
}
],
"group_by": [
"product_identifier",
"product_api_identifier"
],
"methods": [
{
"method_name": "AVG",
"field_name": "elapsed_time"
}
]
}
```
##### Response
201400 application/json400 text/html
application/json Copy Ok.
```
{
"query_id": "c62a1228-fae7-44c8-aebe-8706ecfb9fc4",
"status": "IN_PROGRESS"
}
```
application/json Copy Failed Creation.
```
{
"message": "Error in creating metric "
}
```
text/html Copy Failed Creation.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `date`required | `object` | Date filter and interval specification |
| `start_date`required | `string` | If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format.Example `2021-08-13T00:00:00` |
| `end_date`required | `string` | If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format.Example `2021-08-13T23:59:59` |
| `interval` | `object` | Date interval |
| `type`required | `string` | Interval type`day``hour``minute``second`Example `minute` |
| `value`required | `integer` | Interval valueExample `1` |
| `filters` | `object[]` | List of filters |
| `field_name`required | `string` | Filter field name`configuration_id``invocation_code``product_api_identifier``product_build_hash``product_identifier``response_collection_id``status``transaction_id`Example `status` |
| `field_value`required | `string` | Filter field valueExample `FAILED` |
| `operator`required | `string` | The operator that will be used for comparison`=` |
| `group_by`required | `string[]` | Field names that will be used for grouping |
| `methods` | `object[]` | Methods that will be applied to grouped metrics |
| `method_name`required | `string` | Method name`AVG``COUNT``SUM`Example `COUNT` |
| `field_name`required | `string` | Field name`configuration_id``elapsed_time``invocation_code``product_api_identifier``product_build_hash``product_identifier``response_collection_id``row``status``transaction_id`Example `row` |
| `callback_url` | `string (uri)` | When query execution is done, this url will be called with resultExample `https://webhook.com/callback` |
| `query_configuration` | `object` | Query configuration |
| `include_timezone` | `boolean` | Includes timezone info and update date format to ISO8601. |
| `include_host_environment` | `boolean` | Includes environment domain info to result set. |
##### Response `201``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `query_id` | `string` | Unique identifier for running query execution |
| `status` | `string` | Status of the query execution |
##### Response `400``application/json`
1 fields
Failed Creation.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message reason why the creation has failed |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `422``application/json`
2 fields
Unprocessable Entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `error` | `string` | Error |
`GET` `/metrics/aggregation/query/{query_id}`
#### Get Health Aggregation Query Result[new]
`get_aggregated_health_query_result`
Get Health Aggregation Query Result
The service retrieves aggregated metric query result. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.
##### Response
200400 application/json400 text/html404
application/json Copy Ok.
```
{
"status": "SUCCEEDED",
"result_csv_file": "https://athena-query-results-1111111111.s3.amazonaws.com/2ff0bc1e-c48e-438a-b82b-418d2d844f0a.csv?&Expires=1665390635",
"metrics": [
{
"time_interval": "2022-10-05 00:00:00",
"product_identifier": "e53e749f-38ec-4435-943f-6d5c6d32bc12",
"product_api_identifier": "087dc8c8-936c-4148-82f6-7f8fe112d48c",
"elapsed_time_avg": 0.0018733719
},
{
"time_interval": "2022-10-07 00:00:00",
"product_identifier": "e53e749f-38ec-4435-943f-6d5c6d32bc12",
"product_api_identifier": "087dc8c8-936c-4148-82f6-7f8fe112d48c",
"elapsed_time_avg": 0.00072799996
},
{
"time_interval": "2022-10-06 00:00:00",
"product_identifier": "e53e749f-38ec-4435-943f-6d5c6d32bc12",
"product_api_identifier": "087dc8c8-936c-4148-82f6-7f8fe112d48c",
"elapsed_time_avg": 0.0010120743
}
]
}
```
application/json Copy Error Response.
```
{
"message": "Bad Request"
}
```
text/html Copy Error Response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-sc-trace-id` required | `string` header | `01GYYMHV78DVPV5TSHPQTJ31X9` | Trace ID |
| `x-api-key` required | `string` header | `` | API key |
| `limit` | `integer` query | `150` | The number of results to return in this request. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `query_id` required | `string` path | `query_id_1` | Query ID received previously with asynchronous query creation |
##### Response `200``application/json`
4 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of the query execution`FAILED``IN_PROGRESS``SUCCEEDED`Example `SUCCEEDED` |
| `result_csv_file` | `string` | Url for query result in CSV formatExample `https://athena-query-results-293107503335.s3.amazonaws.com/1cf6527c-95cc-4998-b273-d3f4b9dd8014.csv?%2Fol&Expires=1661502173` |
| `next_token` | `string` | Indicates next page exist. Using this token next page can retrieve.Example `QVdMejZQT0gzY1I5ZmZCOXF2V1NlQW1Za2xITTNRYWtiVFViRUswYUVScWk2ZFJ3Q0xRRFFaQkx0QXVNVlU3K0JvZU8yTDIzc0RCSGNlcGg0TE5ZdExIeWJNeDlidDBSNkE9PQ==` |
| `metrics` | `object[]` | Metrics |
##### Response `400``application/json`
1 fields
Error Response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Custom Metric Types
`POST` `/post-metric`
#### Create Custom Metrics
`post_custom_metric`
Create custom metric for a specific metric type.
Create custom metric for a specific metric type
##### Request
012
application/json Copy
```
{
"metric_type": "test_27",
"name": "simnlol",
"address": "formiga112",
"product": {
"place": "luzitania",
"sin": "rep_24"
},
"techno": [
69,
21,
12,
24
]
}
```
application/json Copy
```
{
"metric_type": "test_nnn",
"name": "simnlol",
"address": "formiga112",
"product": {
"place": "luzitania",
"sin": "rep_24"
},
"techno": [
69,
21,
12,
24
]
}
```
application/json Copy
```
{
"metric_type": "test_27",
"name": "simnlol",
"address": "formiga112",
"product": {
"place": "nono",
"sin": "rep_24"
},
"techno": [
69,
21,
12,
24
]
}
```
##### Response
201400 0400 1400 text/html403
application/json Copy Created Response
```
{
"resp": "metric sent"
}
```
application/json Copy Error Response
```
{
"error": "metric_type test_nnn does not exist "
}
```
application/json Copy Error Response
```
{
"error": "123 is not of type 'string'\n\nFailed validating 'type' in schema['properties']['product']['properties']['place']:\n {'type': 'string'}\n\nOn instance['product']['place']:\n 123"
}
```
text/html Copy Error Response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `product` | `object` | Metric object |
| `sin` | `string` | Metric field example |
| `place` | `string` | Metric field example |
| `address` | `string` | Metric field example |
| `techno` | `integer[]` | Metric field example |
| `metric_type`required | `string` | Metric field example |
| `name` | `string` | Metric field example |
##### Response `201``application/json`
1 fields
Created Response
| Field | Type | Description |
| --- | --- | --- |
| `resp` | `string` | Response |
##### Response `400``application/json`
1 fields
Error Response
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error Response |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`PUT` `/put-metric-type`
#### Update Metric Type
`update_metric_type`
This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health.
This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health. This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health /post-metric service.
The metric type name is the main reference. The field names can be reference to build a new report.
##### Request
01
application/json Copy
```
{
"metric_type_name": "test_000",
"schema": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"product": {
"type": "object",
"properties": {
"place": {
"type": "string"
},
"sin": {
"type": "string"
}
}
},
"techno": {
"type": "array",
"items": {
"type": "number"
}
}
}
}
}
```
application/json Copy
```
{
"schema": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"product": {
"type": "object",
"properties": {
"place": {
"type": "string"
},
"sin": {
"type": "string"
}
}
},
"techno": {
"type": "array",
"items": {
"type": "number"
}
}
}
}
}
```
##### Response
201400 0400 text/html403
application/json Copy Metric type created response
```
{
"message": "the metric_type was successfully updated"
}
```
application/json Copy Error response
```
{
"error": "error updating metric type: metric_type_name is a required field "
}
```
text/html Copy Error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `schema` | `object` | The metric type schema |
| `type` | `string` | Type declaration example |
| `required` | `string[]` | Required array. All the field which are required in the schema |
| `properties` | `object` | Example fields |
| `product` | `object` | Example fields |
| `type` | `string` | Example type |
| `properties` | `object` | Example fields |
| `address` | `object` | Example fields |
| `type` | `string` | Example type |
| `techno` | `object` | Example Array Field |
| `type` | `string` | Example type |
| `items` | `object` | Example Field |
| `name` | `object` | Example Field |
| `type` | `string` | Example type |
| `metric_type_name` | `string` | Unique identifier of the metric type |
##### Response `201``application/json`
1 fields
Metric type created response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`POST` `/create-metric-type`
#### Create Metric Type
`create_new_metric_type`
This service defines a metric type and its fields, allowing the customer to create their own metrics based on events when a metric is posted to the Health.
This service defines a metric type and its fields, allowing the customer to create their own metrics based on events when a metric is posted to the Health /post-metric service.
The metric type name is the main reference. The field names can be reference to build a new report.
##### Request
01
application/json Copy
```
{
"metric_type_name": "test_000",
"schema": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"product": {
"type": "object",
"properties": {
"place": {
"type": "string"
},
"sin": {
"type": "string"
}
}
},
"techno": {
"type": "array",
"items": {
"type": "number"
}
}
}
}
}
```
application/json Copy
```
{
"schema": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"product": {
"type": "object",
"properties": {
"place": {
"type": "string"
},
"sin": {
"type": "string"
}
}
},
"techno": {
"type": "array",
"items": {
"type": "number"
}
}
}
}
}
```
##### Response
201400 0400 text/html403
application/json Copy Metric type created response
```
{
"message": "the new metric_type was successfully created"
}
```
application/json Copy Error response
```
{
"error": "error creating metric type: metric_type_name is a required field "
}
```
text/html Copy Error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `schema` | `object` | The metric type schema |
| `type` | `string` | Type declaration example |
| `required` | `string[]` | Required array. All the field which are required in the schema |
| `properties` | `object` | Example fields |
| `product` | `object` | Example fields |
| `type` | `string` | Example type |
| `properties` | `object` | Example fields |
| `address` | `object` | Example fields |
| `type` | `string` | Example type |
| `techno` | `object` | Example Array Field |
| `type` | `string` | Example type |
| `items` | `object` | Example Field |
| `name` | `object` | Example Field |
| `type` | `string` | Example type |
| `metric_type_name` | `string` | Unique identifier of the metric type |
##### Response `201``application/json`
1 fields
Metric type created response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Environments Data
`POST` `/register-env`
#### Register Environment and API Key
`store_new_environment_credentials`
Register the environment and api key the customer wants to get in reports.
Register the environment and API key, this will allow Health to retrieve data from one environment to another. The data is migrated daily, the customer can retrieve reports from local and other registered environments.
##### Request
application/json Copy .
```
{
"host": "test2.staircaseapi.com\"",
"api-key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
##### Response
400403
text/html Copy 400 response.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `host`required | `string` | The environment hostExample `health.staircaseapi.com` |
| `api-key`required | `string (api-key)` | The api-key used in order to access APIs in the hostExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `201``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | The environment was stored successfully |
##### Response `400``application/json`
1 fields
400 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error in storing the environment invalid host |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
### Report Subscription
`POST` `/report-subscription`
#### Create Report Subscription
`report-subscription`
Subscription to receive a report through Slack notification.
Subscription to receive a report through Slack notification. Specify the period either by days, week, or month, and the filters to apply.
You can subscribe to the following reports:
- Partner Report: Subscribe to receive the Partner report. See this link for more information.
- Products by operation status: Subscribe to receive the Product By Operation Status Report. See this link for more information.
- Summary Reports: Subscribe to receive the Summary Report by Status. See this link for more information.
- Products by unique transactions report: Subscribe to receive the Unique Transactions By Product Report. See this link for more information.
- Custom reports created in the service /build-report
The Slack media type is currently allowed. A token must be provided to send the notification. After the subscription, the user will receive the report through a post with the results in the configured period.
Follow this link to choose or create new apps in Slack. Use the app token "Bot User OAuth Token"
##### Request
Example dailyExample cron dailyExample [x] daysExample weeklyExample monthlyCustom Report Example
application/json Copy
```
{
"subscription_name": "no5",
"media": "slack",
"send_to_id": "slack-channel-name",
"period": "1d",
"products": [
"employment",
"income",
"Health"
],
"environments": [
"account.staircaseapi.com",
"health.staircaseapi.com"
],
"report_type": "summary_report",
"token": ""
}
```
application/json Copy
```
{
"subscription_name": "no5",
"media": "slack",
"send_to_id": "slack-channel-name",
"cron": "0 9,16 * * *",
"products": [
"employment",
"income",
"Health"
],
"environments": [
"account.staricaseapi.com",
"health.staircaseapi.com"
],
"report_type": "summary_report",
"token": ""
}
```
application/json Copy
```
{
"subscription_name": "no3",
"media": "slack",
"send_to_id": "slack-channel-name",
"period": "15d",
"products": [
"employment",
"income",
"Health"
],
"environments": [
"account.staircaseapi.com",
"health.staircaseapi.com"
],
"partners": [
"atomic",
"citadel"
],
"report_type": "partner_report",
"token": ""
}
```
application/json Copy
```
{
"subscription_name": "no2",
"media": "slack",
"send_to_id": "slack-channel-name",
"period": "1w",
"products": [
"employment",
"income",
"Health"
],
"environments": [
"account.staircaseapi.com",
"health.staircaseapi.com"
],
"report_type": "product_unique_transactions_report",
"token": ""
}
```
application/json Copy
```
{
"subscription_name": "no1",
"media": "slack",
"send_to_id": "slack-channel-name",
"period": "1m",
"products": [
"employment",
"income",
"Health"
],
"environments": [
"account.staircaseapi.com",
"health.staircaseapi.com"
],
"report_type": "product_unique_transactions_report",
"token": ""
}
```
application/json Copy
```
{
"media": "slack",
"subscription_name": "no2",
"send_to_id": "slack-channel-name",
"period": "15d",
"report_type": "custom_report_name",
"token": ""
}
```
##### Response
201400 0400 1400 2400 text/html403
application/json Copy Subscription success response
```
{
"message": "Subscription successfully created"
}
```
application/json Copy Subscription error response
```
{
"error": "period field is invalid. format allowed: d, w, m "
}
```
application/json Copy Subscription error response
```
{
"error": "the Subscription solo already exists"
}
```
application/json Copy Subscription error response
```
{
"error": "There is no custom report with the name: cabuc"
}
```
text/html Copy Subscription error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Request body`application/json`
11 fields
| Field | Type | Description |
| --- | --- | --- |
| `subscription_name`required | `string` | Unique Identifier of the Subscription |
| `group_by` | `string` | Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id. It is only used in report type product_by_operation_status or partner report |
| `period`required | `string` | The period is sent using d for days, w for weeks and m for months, the number always goes first e.g. 3w |
| `cron`required | `string` | The scheduler definition is required for cumulative reports. Currently, supports only daily reports. Example of scheduler definition "0 9,16 * * *" → Get report between 00:00 - 09:00 and 00:00 - 16:00 for every day. |
| `environments` | `string[]` | Environments |
| `send_to_id`required | `string` | Slack channel name or Member ID (For private DM) |
| `media`required | `string` | The only type allowed at the moment is slack |
| `products` | `string[]` | List of products used in the query to build the reports which will be sent |
| `partners` | `string[]` | List of partners (only for report_type = partner_report) used in the query to build the reports which will be sent |
| `token` | `string` | In order to use it to send reports through slack this Field is required, the app token must be authorized in the User Token Scopes with files:write |
| `report_type` | `string` | The report name (partner_report, summary_report, product_by_operation_status and product_unique_transactions_report) or Custom report name |
##### Response `201``application/json`
1 fields
Subscription success response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Subscription error response
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`POST` `/error-subscription`
#### Create Error Report Subscription
`create_error_subscription`
This service sends a notification when an error is posted for a product service endpoint in Health.
##### Request
application/json Copy
```
{
"media": "slack",
"subscription_name": "my-error-subscription",
"send_to_id": "U04SR512392R",
"products": [
"Account",
"employment"
],
"token": ""
}
```
##### Response
201400 0400 text/html403
application/json Copy Success Response
```
{
"message": "Subscription successfully created"
}
```
application/json Copy Error Response
```
{
"error": "products is a required field"
}
```
text/html Copy Error Response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `` | Key |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `subscription_name` | `string` | Unique Identifier of the Subscription |
| `send_to_id` | `string` | Slack channel name or Member ID (For private DM) |
| `media` | `string` | The only type allowed at the moment is slack |
| `products` | `string[]` | List of products used in the query to build the reports which will be sent |
| `token` | `string` | In order to use it to send reports through slack this Field is required, the app token must be authorized in the User Token Scopes with files:write |
##### Response `201``application/json`
1 fields
Success Response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Error Response
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
`DELETE` `/delete-subscription/{subscription_id}`
#### Delete Report Subscription
`delete_subscription_id`
This service allows removing a notification subscription.
This service allows removing a notification subscription, the subscription name must be provided. After deleting the subscription, the notification will not be received through slack.
##### Response
200 0200 2400403404
application/json Copy Auto generated using Swagger Inspector
```
{
"message": "subscription no2 successfully deleted"
}
```
application/json Copy Auto generated using Swagger Inspector
```
{
"message": "subsription te99 not found"
}
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
| `subscription_id` required | `string` path | `MNe` | Unique identifier of a subscription which will be deleted. |
##### Response `200``application/json`
1 fields
Auto generated using Swagger Inspector
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`DELETE` `/delete-error-subscription/{subscription_id}`
#### Delete Report Error Subscription
`delete-error-subscription`
This service allows removing a notification subscription.
This service allows removing a notification subscription, the subscription name must be provided. After deleting the subscription, the notification will not be received through Slack.
##### Response
200 0200 2400403404
application/json Copy Auto generated using Swagger Inspector
```
{
"message": "subscription no2 successfully deleted"
}
```
application/json Copy Auto generated using Swagger Inspector
```
{
"message": "subsription te99 not found"
}
```
text/html Copy Bad request.
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
text/html Copy Not found.
```
\r\n400 Bad Request\r\n\r\n404 Not found
\r\n\r\n\r\n
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
| `subscription_id` required | `string` path | `MNe` | Unique identifier of a subscription which will be deleted. |
##### Response `200``application/json`
1 fields
Auto generated using Swagger Inspector
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Bad request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Not found.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message. |
`GET` `/get-subscriptions`
#### Retrieve All Report Subscriptions
`get_all_subscription`
It retrieves a list of subscriptions registered, all subscriptions send a notification with the report type selected, the method, and the send_to_id.
##### Response
200400403
application/json Copy Subscription data.
```
{
"subscriptions": [
{
"subscription_name": "ass",
"media": "slack",
"send_to_id": "test",
"period": "15d",
"cron": null,
"report_type": "summary_report",
"query_info": {
"customer_x_api_key": "iaia-222-4ca4-a061-xxxaoaoao",
"environments": [
"account.staircaseapi.com",
"health.staircaseapi.com"
],
"products": [
"employment",
"income",
"Health"
]
}
}
],
"error_subscriptions": [
{
"subscription_name": "11",
"media": "slack",
"query_info": {
"products": [
"Health"
]
}
}
]
}
```
text/html Copy 400 Bad Request
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Response `200``application/json`
2 fields
Subscription data.
| Field | Type | Description |
| --- | --- | --- |
| `subscriptions` | `object[]` | Subscription data. |
| `period` | `string` | Period. |
| `cron` | `string` | Period. |
| `send_to_id` | `string` | ID where it will be sent. |
| `subscription_name` | `string` | Unique identifier of the subscription. |
| `media` | `string` | Slack the only value allowed at the moment. |
| `report_type` | `string` | Type of the report. |
| `query_info` | `object` | Filters detail |
| `customer_x_api_key` | `string` | It is the key required in order to use the API. Filters by customer_api_key. |
| `environments` | `string[]` | Environments |
| `products` | `string[]` | List of products used in the query to build the reports which will be sent |
| `error_subscriptions` | `object[]` | Error Subscriptions |
| `subscription_name` | `string` | Unique identifier of the subscription. |
| `send_to_id` | `string` | ID where it will be sent. |
| `query_info` | `object` | Filters detail |
| `products` | `string[]` | List of products for error metrics. |
| `media` | `string` | Slack the only value allowed at the moment. |
##### Response `400``application/json`
1 fields
400 Bad Request
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
### Reports
`GET` `/summary_report_by_status`
#### Retrieve Summary Report by Status
`get_report_summary_report_by_status`
This report brings the total number of metrics by status.
This report brings the total number of metrics by status. You can get the following information about your products by using this report:
- The metrics posted for per product
- The metrics that succeeded per product.
- The metrics that failed, this means that an error or exception occurred in the product while processing one of the services.
##### Response
200400 Error Response Example400 text/html403
application/json Copy Example Success Response
```
{
"report": {
"Items": [
{
"product_name": "service-decision-api-dev",
"host_env": "account.staircaseapi.com",
"succeeded": "2",
"total": 2
},
{
"product_name": "income-dev",
"host_env": "account.staircaseapi.com",
"succeeded": "2",
"total": 2
},
{
"product_name": "assessments",
"host_env": "health.staircaseapi.com",
"succeeded": "9",
"total": 9
},
{
"product_name": "employment",
"host_env": "health.staircaseapi.com",
"succeeded": "21",
"failed": "5",
"total": 26
}
],
"Next_token": " "
}
}
```
application/json Copy Error response
```
{
"message": "error: end_date is a required field"
}
```
text/html Copy Error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `start_date` required | `string` query | `2021-04-01` | Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` required | `string` query | `2021-05-30` | Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `environments` | `string` query | `account.staircaseapi.com,health.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `products` | `string` query | `employment,income` | List of product names to filter, the report will bring all product names if this input is not available. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | report |
| `Items` | `object[]` | Items |
| `total` | `integer` | Total |
| `host_env` | `string` | Environment |
| `product_name` | `string` | Product name |
| `succeeded` | `string` | Succeeded |
| `failed` | `string` | Failed |
| `Next_token` | `string` | Next token pagination purpose |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
`GET` `/partner_report`
#### Retrieve Partner Report
`get_report_partner_report`
This report retrieves the number of transactions and the last operation status by partner in the given timeframe period.
The Mortgage products operations with a data partner are registered from the beginning of the transaction until it is completed. This report retrieves the number of transactions and the last operation status by partner in the given timeframe period.
The data will be aggregated between all environments registered. See this link for more information.
##### Response
200400403
application/json Copy Success Response
```
{
"report": {
"Items": [
{
"product_name": "employment",
"partner": "atomic",
"total_by_status": {
"STARTED": 1,
"IN_PROGRESS": 3,
"COMPLETED": 1
},
"total": 5
},
{
"product_name": "income",
"partner": "truework",
"total_by_status": {
"STARTED": 1,
"COMPLETED": 2,
"CANCELLED": 1
},
"total": 4
},
{
"product_name": "employment",
"partner": "truework",
"total_by_status": {
"STARTED": 2,
"COMPLETED": 3,
"CANCELLED": 6
},
"total": 11
},
{
"product_name": "employment",
"partner": "citadel",
"total_by_status": {
"STARTED": 1,
"IN_PROGRESS": 4
},
"total": 5
},
{
"product_name": "employment",
"partner": "argyle",
"total_by_status": {
"IN_PROGRESS": 5
},
"total": 5
},
{
"product_name": "employment",
"partner": "verix",
"total_by_status": {
"COMPLETED": 6
},
"total": 6
}
]
}
}
```
application/json Copy Auto generated using Swagger Inspector
```
{
"message": "error: end_date is a required field"
}
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
7
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `start_date` required | `string` query | `2021-05-01` | Filters the data by a range of dates starting with this date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` required | `string` query | `2021-05-31` | Filters the data until this date. Date must be in ISO8601 format: YYYY-MM-DD |
| `environments` | `string` query | `documentation.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `products` | `string` query | `employment,income` | List of product names to filter, the report will bring all product names if this input is not available. |
| `group_by` | `string` query | `request_collection_id` | Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id. |
| `partners` | `string` query | `atomic,citadel` | The name of the data partners in Mortgage products. |
| `x-api-key` | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Key |
##### Response `200``application/json`
1 fields
Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Report |
| `Items` | `object[]` | Items |
| `total` | `integer` | Total |
| `partner` | `string` | Partner |
| `product_name` | `string` | Product name |
| `total_by_status` | `object` | Total |
| `COMPLETED` | `integer` | Operation status |
##### Response `400``application/json`
1 fields
Auto generated using Swagger Inspector
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `504``application/json`
1 fields
504 Timeout response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint request timed out |
`GET` `/product_by_operation_status`
#### Retrieve Product by Operation Status Report
`get_report_product_by_operation_status`
This report retrieves the number of transactions and the last operation's status for the given timeframe period.
Every single Staircase service endpoint (such as POST /persistence/transactions or POST /aus/underwrite) is required to provide operation status updates to denote the progress of a transaction in its execution. For more information and examples see this link
This report retrieves the number of transactions and the last operation's status for the given timeframe period.
##### Response
200400 Error Response Example400 text/html403
application/json Copy Example Success Response
```
{
"report": {
"Items": [
{
"product_name": "get-code-clone",
"host_env": "health.staircaseapi.com",
"total_by_status": {
"STARTED": 11,
"IN PROGRESS": 21
},
"total": 32
}
]
},
"next_token": "eyJOZXh0VG9rZW4iOiAiQVJ0Zkl4L2QvOVdnRUpBTFJidWNQU0c0MVhrS3lTVURJU3JobCt3dHEvaUZxM3NNa0R2S3NSS0pVdmh4RVZQME5CRzBtS2lGTnF0ZGZlMTBpS3RsM09EZTBSZ0I0OS8rbXc9PSIsICJRdWVyeUV4ZWN1dGlvbklkIjogIjFhYzgwMDUyLTgwNzktNDA4YS04OWU3LTlmM2Q4NWEzZWVjMSJ9"
}
```
application/json Copy Error response
```
{
"message": "error: end_date is a required field"
}
```
text/html Copy Error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
7
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `start_date` required | `string` query | `2021-04-01` | Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` required | `string` query | `2021-05-30` | Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `environments` | `string` query | `account.staircaseapi.com,health.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `products` | `string` query | `employment,income` | List of product names to filter, the report will bring all product names if this input is not available. |
| `group_by` | `string` query | `request_collection_id` | Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Report |
| `Items` | `object[]` | Items |
| `total` | `integer` | Total |
| `host_env` | `string` | Environment |
| `product_name` | `string` | Product Name |
| `IN PROGRESS` | `string` | Operation Status |
| `STARTED` | `string` | Operation Status |
| `Next_token` | `string` | Next token pagination |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
`GET` `/product_unique_transactions_report`
#### Retrieve Unique Transactions By Product Report
`get_report_product_unique_transactions_report`
This report brings the total number of unique transactions by status and a breakdown per day.
This report brings the total number of unique transactions by status and a breakdown per day. We can have multiple metrics registered for the same transaction, this report will bring unique transaction id count.
You can get the following information about your products by using this report:
- The transactions processed per product.
- The transactions that were processed by a service endpoint and succeeded.
- The transactions that were processed by a service endpoint and reported an exception or error.
##### Response
200400 Error Response Example400 text/html403
application/json Copy Example Success Response
```
{
"report": {
"Items": [
{
"product_name": "Health",
"host_env": "account.staircaseapi.com",
"total_unique_transactions": 71,
"failed": 0,
"succeeded": 71,
"per_day": [
{
"day": "2021-05-24",
"succeeded": 7,
"unique_transactions": 7
},
{
"day": "2021-05-25",
"succeeded": 31,
"unique_transactions": 31
},
{
"day": "2021-05-26",
"succeeded": 12,
"unique_transactions": 12
},
{
"day": "2021-05-27",
"succeeded": 8,
"unique_transactions": 8
},
{
"day": "2021-05-28",
"unique_transactions": 0
},
{
"day": "2021-05-29",
"unique_transactions": 0
},
{
"day": "2021-05-30",
"unique_transactions": 0
},
{
"day": "2021-05-31",
"unique_transactions": 0
},
{
"day": "2021-06-01",
"succeeded": 6,
"unique_transactions": 6
},
{
"day": "2021-06-02",
"succeeded": 7,
"unique_transactions": 7
}
]
}
]
},
"next_token": "DUyLTgwNzktNDA4YS04OWU3LTlmM2Q4NWEzZWVjMSJ9"
}
```
application/json Copy Error response
```
{
"message": "error: end_date is a required field"
}
```
text/html Copy Error response
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `start_date` required | `string` query | `2021-04-01` | Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `end_date` required | `string` query | `2021-05-30` | Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD |
| `environments` | `string` query | `account.staircaseapi.com,health.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `products` | `string` query | `employment,income` | List of product names to filter, the report will bring all product names if this input is not available. |
| `next_token` | `string` query | `000000000000` | The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.) |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Report |
| `Items` | `object[]` | Item |
| `total_unique_transactions` | `integer` | Total |
| `host_env` | `string` | Environment |
| `per_day` | `object[]` | Total per day |
| `day` | `string` | Date |
| `unique_transactions` | `integer` | Total per day |
| `succeeded` | `integer` | Total Succeeded per day |
| `product_name` | `string` | Product name |
| `Next_token` | `string` | Next token pagination |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
`GET` `/cost-report-day`
#### Retrieve Cost Report Grouped by day
`get_cost_report_by_day`
Retrieve Cost Report Grouped by day.
##### Response
200400 0400 2400 3403
application/json Copy Example Success Response
```
{
"report": {
"data": {
"cost_category": "customer",
"total_cost": 10958155,
"total_transaction_count": 115349,
"dates": [
{
"date": "2021-12-04",
"total_cost": 151240,
"total_transaction_count": 1592,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 151240,
"total_transaction_count": 1592,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 151240,
"total_transaction_count": 1592
}
]
}
]
},
{
"date": "2021-12-05",
"total_cost": 303810,
"total_transaction_count": 3198,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 303810,
"total_transaction_count": 3198,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 303810,
"total_transaction_count": 3198
}
]
}
]
},
{
"date": "2021-12-06",
"total_cost": 534375,
"total_transaction_count": 5625,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 534375,
"total_transaction_count": 5625,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 534375,
"total_transaction_count": 5625
}
]
}
]
}
]
}
}
}
```
application/json Copy Error response
```
{
"message": "error: cost_category is a required field"
}
```
application/json Copy Error response
```
{
"message": "error: product_name is a required field"
}
```
application/json Copy Error response
```
{
"message": "error: start_date is a required field"
}
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `end_date` required | `string` query | `2021-10-18` | end_date |
| `products` | `string` query | `employment,income` | List of product names to filter |
| `cost_category` required | `string` query | `customer` | Cost Category (customer, partner) |
| `start_date` required | `string` query | `2021-10-12` | start_date |
| `environments` | `string` query | `account.staircaseapi.com,health.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Response object |
| `Items` | `object[]` | Array of Items |
| `cost_in_cents` | `string` | Cost in USD cents. |
| `day` | `string` | The date. |
| `product_name` | `string` | Product_name |
| `cost_category` | `string` | Cost Category |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
`GET` `/cost-report-month`
#### Retrieve Cost Report of a given month
`get_cost_report_month`
Retrieve Cost Report of a given month.
##### Response
200400 0400 1403
application/json Copy Example Success Response
```
{
"report": {
"data": {
"cost_category": "customer",
"total_cost": 11133050,
"total_transaction_count": 117190,
"dates": [
{
"date": "2021-12",
"total_cost": 11133050,
"total_transaction_count": 117190,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 11133050,
"total_transaction_count": 117190,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 11133050,
"total_transaction_count": 117190
}
]
}
]
}
]
}
}
}
```
application/json Copy Error response
```
{
"message": "error: month is a required field"
}
```
application/json Copy Error response
```
{
"message": "error: cost_category is a required field"
}
```
application/json Copy 403 response
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `month` required | `string` query | `10` | Month |
| `products` | `string` query | `employment,income` | List of product names to filter |
| `cost_category` required | `string` query | `customer` | Cost Category (customer, partner) |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Response object |
| `Items` | `object[]` | Array of Items |
| `cost_in_cents` | `string` | Cost in USD cents. |
| `day` | `string` | The date. |
| `product_name` | `string` | Product_name |
| `cost_category` | `string` | Cost Category |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 response
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | URL |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
500 response.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Internal server error |
`GET` `/cost-report`
#### Retrieve Cost Report of a given interval
`get_cost_report`
Retrieve Cost Report of a given interval.
##### Response
200400 0400 1400 3
application/json Copy Example Success Response
```
{
"report": {
"data": {
"cost_category": "customer",
"total_cost": 2081260,
"total_transaction_count": 21908,
"dates": [
{
"date": "2021-12-24",
"total_cost": 913235,
"total_transaction_count": 9613,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 913235,
"total_transaction_count": 9613,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 913235,
"total_transaction_count": 9613
}
]
}
]
},
{
"date": "2021-12-25",
"total_cost": 783940,
"total_transaction_count": 8252,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 783940,
"total_transaction_count": 8252,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 783940,
"total_transaction_count": 8252
}
]
}
]
},
{
"date": "2021-12-26",
"total_cost": 384085,
"total_transaction_count": 4043,
"environments": [
{
"environment_name": "health.staircaseapi.com",
"total_cost": 384085,
"total_transaction_count": 4043,
"products": [
{
"product_name": "Health",
"cost_in_cents": 95,
"total_cost": 384085,
"total_transaction_count": 4043
}
]
}
]
}
]
}
}
}
```
application/json Copy Error response
```
{
"message": "error: end_date is a required field"
}
```
application/json Copy Error response
```
{
"message": "error: cost_category is a required field"
}
```
application/json Copy Error response
```
{
"message": "error: product_name is a required field"
}
```
##### Parameters
7
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `end_date` required | `string` query | `2021-10-18` | end_date |
| `products` | `string` query | `employment,income` | List of product names to filter |
| `cost_category` required | `string` query | `customer` | Cost Category (customer, partner) |
| `start_date` required | `string` query | `2021-10-12` | start_date |
| `date_range_type` | `string` query | `daily` | Allows grouping costs by selected date type. |
| `environments` | `string` query | `account.staircaseapi.com,health.staircaseapi.com` | List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports. |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API key |
##### Response `200``application/json`
1 fields
Example Success Response
| Field | Type | Description |
| --- | --- | --- |
| `report` | `object` | Response object |
| `Items` | `object[]` | Array of Items |
| `cost_in_cents` | `string` | Cost in USD cents. |
| `day` | `string` | The date. |
| `product_name` | `string` | Product_name |
| `cost_category` | `string` | Cost Category |
##### Response `400``application/json`
1 fields
Error response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
## Canonical model
- `address`
- `address`
## Property data it reads
- address
## Errors
`400``403``404``422``500``502``504`
## More in Shipping
- Previous product: Deploy
- Next product: Pipeline
---
# Pipeline
# Pipeline
The orchestration primitive that runs the shipping stages as one sequence.
The stages exist as separate products — Code, Assess, Build, Deploy, Comply and publication through Marketplace — and this is the thing that runs them in order, as a single automated action against a repository.
Keeping the stages independently callable and the sequence separate is what allowed a stage to be run alone. Re-running assessment against a repository without deploying it is a normal operation, not a special mode.
What is recorded is the action itself plus the deployment surface behind it — creating a pipeline, deploying it, and the dynamic form that deploys one built for a specific service.
## Operations
### Action
`POST` `/run-action`
#### Run Action
`run_action`
Run Action.
#### Run Action
##### Other responses
`201`
### Operations
`POST` `/deployment`
#### Run deployment to root
Run deployment process for given service from branch to the root account
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `branch`required | `string` | Git branch to use |
| `environment`required | `string` | can be dev or test |
| `project`required | `string` | name of project(repository name) |
##### Response `201``application/json`
3 fields
Deployment created
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status of triggered deployment |
| `message` | `string` | Information about deployment |
| `execution_id` | `string` | ID of deployment using which user can retrieve status |
`GET` `/deployment/{execution_id}/status`
#### Get deployment status
Get deployment status for the deployment to any account using execution_id
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `execution_id` required | `string` path | — |
##### Response `200``application/json`
2 fields
Status for provided execution
| Field | Type | Description |
| --- | --- | --- |
| `deployment_status` | `string` | Status of deployment |
| `description` | `string` | Deployment description |
##### Response `400``application/json`
2 fields
Provided execution id does not exists
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `description` | `string` | Error description |
`POST` `/dynamicDeployment`
#### Run deployment on given account
Run deployment process for given service from branch at any accoun
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `branch`required | `string` | use github sha commit |
| `project`required | `string` | name of project(repository name) |
| `bucket`required | `string` | name of bucket where place artifacts for sandbox:sandbox-account-artifacts |
| `bundle_id`required | `string` | sha commit |
| `accessKey`required | `string` | access key for account, ask devops for providing keys |
| `secretKey`required | `string` | secret key for account, ask devops for providing keys |
##### Other responses
`200`
`POST` `/v3/deployments`
#### Start deployment pipeline
Deploy service to a given account
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `project_name`required | `string` | name of github repository |
| `access_key`required | `string` | environment credentials |
| `secret_key`required | `string` | environment credentials |
| `env` | `string` | — |
| `branch` | `string` | branch to be deployed if different from master |
| `domain_name`required | `string (hostname)` | domain name of the environment to deploy |
##### Response `201``application/json`
1 fields
Pipeline execution created
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | — |
##### Other responses
`400`
`GET` `/v3/deployments/{bundle_id}`
#### Get status of current deployment
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `bundle_id` required | `string (uuid)` path | — |
##### Response `200``application/json`
2 fields
Deployment status
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string (uuid)` | — |
| `status` | `string` | — |
##### Other responses
`404`
## Errors
`400``404`
## More in Shipping
- Previous product: Health
---
# How this was built
# How this was built
A fixed five-artifact shape for every vendor integration, a build rule that failed any endpoint without documentation, and a generator for new jurisdictions.
Three machines, each doing the same thing in a different domain: fixing the shape of a unit of work so that adding the next one costs less than the last.
The integration factory fixed the shape of a vendor. The build rule fixed the shape of a service. The jurisdiction generator fixed the shape of a data source.
## The integration factory
A vendor integration is five artifacts in a fixed shape, none of which touches product code.
- **connection configuration** — The wire protocol. One repository per vendor API call, not per vendor.
- **language configuration** — The field mapping between the vendor's vocabulary and the canonical model.
- **flow file** — The four-way translation: canonical request, vendor request, vendor response, canonical response.
- **waterfall priority** — One line naming where this vendor sits in the vertical's ordering.
- **status call** — Activating the vendor for a lender, optionally with the lender's own credentials.
## Translation, the artifact that makes one contract serve every vendor
A translation is declared, not coded. Each one names four vocabularies: what the canonical model sends in, what the vendor's request expects, what the vendor's response returns, and what comes back out as canonical. Each row below is one such declaration, read from the committed configuration for that integration.
The consequence is that a required-field rule stated once at the model propagates into every caller's own field names. A caller working in its own dialect receives the validation error against its own paths, with no per-caller implementation, and a product's contract never changes when a vendor is added.
| Provider | Flow | Canonical in | Vendor in | Vendor out | Canonical out | Lender credentials |
| --- | --- | --- | --- | --- | --- | --- |
| Argyle | `income` | `staircase-graph` | `income-input` | `income-argyle-output` | `staircase-graph` | supported |
| Essent | `essent-insurance-flow` | `staircase-graph` | `essent-input` | `essent-output` | `staircase-graph` | not enabled |
| Plaid | `asset` | `staircase-graph` | `asset-input` | `asset-plaid-output` | `staircase-graph` | not enabled |
| Xactus | `credit-verify` | `staircase-graph` | `credit-input` | `credit-mismo231` | `staircase-graph` | — |
A language configuration carries a ruleset in each direction, rules with stable identifiers, and an error-message mapping — so two vendors returning different codes for the same condition surface as one code to the caller.
Test requirements are part of the contract: a case per rule, a case per enumeration value, warning assertions, coverage assertions, and validation of the resulting canonical collection against the model.
Bulk translation runs on Spark. The recorded measurement is 7,848 translations in 299 seconds across 20 executors.
## The endpoint documentation rule
A rule in the build gate failed any build containing an endpoint that did not appear in its own specification. Not a warning, not a report — a failed build. Every service therefore carries a specification that matches what it actually serves, at a canonical path.
A documentation rule enforced by the build is a different thing from a documentation culture. One of them survives six years without anybody maintaining it.
The gate itself: Assess · the pipeline it runs in: Build
## How the waterfall runs
- A vendor that answers asynchronously by webhook resumes the same execution as one that answers synchronously. The waterfall does not distinguish between them.
- On a vendor failure with attempts remaining, a new result collection is persisted, stamped with the vendor name and a failure result, before the next vendor is tried. The complete sequence of who was tried, in what order, and what each returned is queryable after the fact rather than reconstructed from logs.
- A lender routes through Staircase's own vendor contract or supplies its own credentials, per vendor, with no code change.
- Every invocation carries a dry-run branch, and individual vendor flows carry their own dry-run state returning a recorded fixture.
## The jurisdiction generator
The same discipline, pointed at public records. One sample page in, an extraction pipeline out, validated against the same canonical classes every other jurisdiction uses. Coverage stops being a vendor negotiation and becomes a compute question.
1. One sample page in — A single record from the jurisdiction's own portal is the whole input. No schema negotiation, no vendor conversation, no bulk file.
1. Retrieve the worked examples — Every jurisdiction already solved is retrieved as a worked example, so the marginal cost of the five-hundredth source approaches the marginal cost of the fifth.
1. An agent writes the extraction pipeline — The output is a jurisdiction-specific extraction pipeline, not a one-off scrape — versioned, testable, and re-runnable.
1. Validate against the canonical model — Extracted records are validated against the published class definitions before they enter the dataset, so a new jurisdiction cannot introduce a shape no downstream consumer understands.
1. Publish as a queryable, agent-callable surface — The jurisdiction becomes a query table an agent can reach directly, and a completeness report says what it does not have.
The onboarding contract is five scripts per jurisdiction — owner, structure, layout and utility mapping, then an assembler that reads the raw capture plus those four outputs and writes the canonical record set. The four mappings run in parallel; the assembler runs last.
The scripts are generated. A graph agent reads one sample page plus the seed address record and writes the five, then the output is validated against the class schemas and the resulting error list is fed back in as context for the next attempt. The recorded cost of a generation run is about an hour of wall clock and roughly 10 dollars of tokens.
Generation retrieves from jurisdictions already solved: every function in the existing transform corpus is indexed by embedding, so authoring the next jurisdiction's structure mapping starts from the closest working implementations rather than from nothing.
Enumerations are the failure surface. A generated script throws on an unmapped source value rather than assigning a default, which is what keeps a plausible wrong value out of the dataset.
## Where it reaches today
Coverage is reported from the deployed configuration rather than from a record count. A jurisdiction appears here when a configuration names it; a surface it does not name is absent rather than estimated.
Property records and permits are separate surfaces with separate coverage. Permits are issued by municipalities rather than counties, so a jurisdiction serving property records does not automatically serve permits, and the two are reported apart.
| Jurisdiction | State | Property records | Permits |
| --- | --- | --- | --- |
| Lee | Florida | served | — |
| Palm Beach | Florida | served | — |
| Miami-Dade | Florida | served | — |
| Orange | Florida | served | — |
| Santa Clara | California | served | served |
### Florida, as the reference case for coverage
The Florida jurisdictions above are what a served market looks like: records validated against the canonical classes, a query surface an agent calls directly, and completeness reported per source rather than assumed. A tool that says what it does not have is the strongest available credibility signal, and it is already how this surface behaves.
### Texas, as the reference case for the mechanism
No Texas jurisdiction is configured. Serving one means running the same five steps above against a jurisdiction with no committed configuration behind it, which is what entering a market costs when the constraint is data rather than desire.
---
# Staircase
## Data
### Mortgage model
- address
- credit
- document
- employment
- employment_income
- fee
- finance_relation
- income
- insurance
- loan
- mortgage_application
- mortgage_plan
- payment
- person
- person_credit
- person_income
- pricing_schema
- property
- property_tax
- tax
### Property model
- property_seed
- unnormalized_address
- address
- parcel
- person
- property
- tax
- tax_jurisdiction
- tax_exemption
- lot
- sales_history
- file
- layout
- flood_storm_information
- structure
- property_improvement
- utility
- deed
- geometry
- appliance
- homeowners_association
- hoa_policy
- loan
- property_ranking_overall
- inspection
- environment_characteristics
- safety_security
- transportation_access
- school
- tax_authority
## Products
### Verification
Is what the borrower told us true?
- Asset
- Credit
- Employment
- Identity
- Income
- Tax
### Assessment
What is the collateral, and what is it worth?
- Appraisal
- Listing
- Property
- Tax
- Valuation
### Eligibility
Will someone buy this loan?
- Compliance
- Fraud
- Government
- Insurance
- Rating
### Contract
What are the documents and the numbers?
- Document
- Electronic
- Fee
- Insurance
- Lexicon
- Notary
- Price
- Signature
- Title
### Automation
Move the loan without a human.
- Approval
- Boarding
- Income
### Integration
Reach the systems of record.
- Closing
- LOS
- POS
- Servicing
### Validation
Are the artifacts we produced correct?
- Appraisal
- Document
- Title
### Adapters
Connect to the loan origination system itself.
- LOS
## Providers
### Asset verification
- Equifax
- Finicity
- Plaid
### Credit
- CBC / Factual Data
- Equifax
- Informative Research
- MeridianLink
- Sharper Lending
- Xactus
### Document AI / OCR / extraction
- Ephesoft
- Mindee
- Ocrolus
- SoftworksAI
### Employment / Income verification
- Argyle
- Atomic
- Citadel
- Equifax
- Experian
- Finicity
- Pinwheel
- Truework
- Truv
- Wage
### GSE / AUS
- Fannie Mae
- Freddie Mac
- Wilqo
### Identity
- MeridianLink
- Prove
### LOS / origination platforms
- Blend
- Byte Software
- ICE Mortgage Technology
- LendingPad
- Sales Boomerang
### Mortgage insurance
- Arch MI
- Enact
- Essent
- MGIC
- National MI
- Radian
### Pricing / PPE
- Optimal Blue
### Property / valuation
- RPR
### Servicing
- Valon
### Title / closing / notary / signature
- DocuSign
- Docutech
- Stavvy
## Delivery
### Distribution
What happens to a build before somebody can call it?
- Access
- Console
- Environment
- Finance
- Host
- Marketplace
- Setup
### Shipping
How does code get from a repository to a running service?
- Assess
- Build
- Code
- Comply
- Deploy
- Health
- Pipeline
## Platform
### Data
Where does the canonical record live, and what shapes it?
- Content
- Language
- ML
- Persistence
- Rule
- Site
- Turker
### Integration
How does a product reach a vendor, and how does it run?
- Connection
- Job
- Product
- Workflow
## Agents
### Surfaces
- The network
- Skills
- Registry
- Tools
- Fleet
- Evaluations
- Runtimes
### Routing
- Router
### Data
- Counterparty document expectations
- Data-lake assistant
- Dataset fulfilment
- Knowledge search
- Metric reconciliation
- Model curator
- Pipeline control panel
- Property data exploration
- Public record ingestion
- Question answering
- Report catalog
- Search to production
### Products
- Application document
- Assets
- Co-borrower invitation
- Contact details
- Correction
- Credit
- Declarations
- Demographic details
- Employment and income
- Frequently-asked questions
- Gifts and grants
- Liabilities
- Loan lookup
- Military service
- Mortgage details
- Other income
- Personal identity
- Preapproval letter
- Pricing
- Rate estimate
- Real estate owned
- Residency
- Self-employment income
- Workspace assistant
### Providers
- File sync
- Marketing stack
- Roster workflow
- Send lifecycle
### Delivery
- Analytics instrumentation
- Application scaffolding
- Design implementation
- Design testing
- Interface triage
- Marketplace architecture
- Sharing portals
### Platform
- Audience selection
- Batch workflows
- Capability map
- Channel assembly
- Contact scheduling solver
- Conversation management
- Conversation runtime
- Mail campaign operations
- Message assistant
- Rule editor
- Short links
- Solver services
- Template inventory
### Creating new agents
- Assistant builder
- Audit analyser
- Operations agent builder
- Spend approval
---
# Platform
# Platform
The data and integration substrate every other product is built on.
Two categories. Data holds the graph store, the translation layer, the rules engine, the models and the documentation platform. Integration holds the vendor connector layer, the job scheduler and the registry that defines other products.
Nothing in this family is sold on its own. It is the layer the mortgage and delivery products are assembled from, documented because the shape of the layer explains the shape of everything above it.
- Connection
- Content
- Job
- Language
- ML
- Persistence
- Product
- Rule
- Site
- Turker
- Workflow
---
# Data
# Data
The data substrate: the graph store, the translation layer, the rules engine, the models and the documentation platform.
Where does the canonical record live, and what shapes it?
Everything above this family reads and writes through it. The graph store holds the canonical record with immutable state, so every version of an entity survives and history is a query rather than an audit table. The translation layer maps any caller's own field vocabulary onto the canonical model in both directions. The rules engine expresses the conditions that eligibility and validation test, as data rather than as code.
The remaining products serve the surfaces around those three: document and image models, the content store, the human-review queue, and the documentation platform that generated the developer reference from the ontology.
## Products
In the order the value chain runs.
1. Content has a recorded specification
1. Language has a recorded specification
1. ML has a recorded specification
1. Persistence has a recorded specification
1. Rule has a recorded specification
1. Site has a recorded specification
1. Turker
---
# Content
# Content
The content store and delivery layer behind the documentation and marketing surfaces.
Content is held separately from the applications that render it, so a page's text is edited without a deployment. Site reads from it for product overviews and quickstarts; the marketing surfaces read from it for everything else.
Keeping content out of the build is what allowed documentation edits to move at a different speed from code, which is the only speed that works for either.
One endpoint is recorded against it, which is the honest measure of how thinly this slot was documented rather than of how much it did: the marketing site and the documentation surface both read from the same content service, and neither of them wrote its contract down.
## Operations
### Operations
`GET` `/getting-started`
#### Content for getting-started section
Get content for getting started section
##### Response `200``application/json`
1 fields
Content successfully sent
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
## Errors
`403`
## More in Data
- Next product: Language
---
# Language
# Language
Bidirectional translation between a caller's own field vocabulary and the canonical model, at single-record and bulk scale.
A language is a registered mapping. Language carries the registry, generates and validates rulesets, translates records in both directions, and exposes graph queries in a form a caller can send as structured data rather than as a query language.
Bulk translation runs on a Spark cluster. The measurement on record is 7,848 translations in 299 seconds across 20 executors.
## How it works
This is the mechanism behind any caller keeping its own field names without per-caller code. A vendor's vocabulary and a lender's vocabulary are the same kind of object here — both are registered languages over the same model — which is why the agency mappings sit in the registry alongside the customer ones.
The payoff shows up in validation. A required-field rule declared once at the model surfaces to each caller against that caller's own paths, because the translation runs over the error as well as over the data.
## Operations
### Lexicon
`POST` `/build-payload`
#### Build Payload
`buildPayload`
Build Payload builds a payload based on provided JSONPaths and values.
##### Request
application/json Copy
```
{
"$.deal_sets[0].parties[0].individual.first_name": "John",
"$.deal_sets[0].parties[0].roles[0].party_type": "Borrower",
"$.deal_sets[0].parties[0].roles[0].employers[0].legal_entity_name": "Truework Inc",
"$.deal_sets[0].parties[0].taxpayer_identifiers[0].value": "999-00-0000"
}
```
##### Response
200400403
application/json Copy 200 response
```
{
"deal_sets": {
"deal_set": [
{
"deals": {
"deal": [
{
"parties": {
"party": [
{
"individual": {
"name": "John"
},
"roles": {
"role": [
{
"role_detail": {
"party_type": "Borrower"
},
"borrower": {
"employers": {
"employer": [
{
"legal_entity": {
"legal_entity_detail": {
"full_name": "Truework Inc"
}
}
}
]
}
}
}
]
},
"taxpayer_identifiers": {
"taxpayer_identifier": [
{
"type": "EmployerIdentificationNumber",
"value": "999-00-0000"
}
]
}
}
]
}
}
]
}
}
]
}
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Other responses
`200`
`PUT` `/lexicon`
#### Create/Update Staircase Lexicon
`createUpdateStaircaseLexicon`
Create/Update Staircase Lexicon - for translation between versions
Create/Update Staircase Lexicon replaces mappings for a staircase-to-staircase language.
Replaces previously created mappings - can be in .csv or .json format.
- Lexicon naming based on sc_version_from, sc_version_to params:
- For .csv-based languages - use query parameters.
```
Example: ?sc_version_from=0&sc_version-to=2
```
- For .json-based languages - use .json payload.
```
Example: sc_versions: {sc_version_from: 0, sc_version_to: 2}
```
Translates between Staircase language versions, and is internally named VX_TO_VY - where X is lower, Y is higher version. FromPath and ToPath definitions are defined by sc_version_from and sc_version_to in lexicon definition.
Show the rest Example: Lexicon: V0_TO_V2
Lexicon writer initially writes a lexicon from V0 to V2 - in this case sc_version_from = 0, sc_version_to = 2. Later, wants to add detail, etc. and defines lexicon from V2 to V0. In this case, new lexicon overwrites existing one with same name: V0_TO_V2 - in this case, however, internal definition shows sc_version_from = 2 and sc_version_to = 0.
During runtime, incoming payload indicates sc_version_from and sc_version_to. Forward translation is done if versions match, reverse translation otherwise.
When retrieving Lexicon - must pay close attention to directionality contained within language definition to determine how lexicon was originally written.
Guide for building a .csv-based language
Guide for building a .json-based language
Retrieve a pre-built language to understand how they are constructed.
If the language is given in .csv format, which is more straightforward and can be built by a business analyst, Translator converts the .csv file into the more technical .json format.
##### Request
application/json Copy
```
{
"content_type": "application/json",
"mapping": {
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate"
},
"values_mapping": [
{
"element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
"mapping": [
{
"language_value": "FooBar",
"staircase_value": "HelloWorld"
},
{
"language_value": "WorldHello",
"staircase_value": "BarBaz"
}
]
}
],
"sc_versions": {
"sc_version_from": 0,
"sc_version_to": 2
}
}
```
##### Response
400403
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sc_version_from` required | `integer` query | `1` | .csv-only - staircase-to-staircase language - from version |
| `sc_version_to` required | `integer` query | `1` | .csv-only - staircase-to-staircase language - to version |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `mapping`required | `object` | Mapping object |
| `values_mapping`required | `object[]` | Value mapping array |
| `element`required | `string` | Value mapping element |
| `mapping` | `object[]` | Value mapping array |
| `staircase_value`required | `string` | Staircase value string |
| `language_value`required | `string` | Language value string |
| `unique_arrays` | `object` | Key-value pairs, where key is JSONPath to array of objects, and value is key, that has been unique |
| `merge_arrays` | `object` | Key-value pairs, where key is JSONPath to array which will contain merged elements, and value is an array, which contains JSONPaths to arrays that should be excluded from result and all their elements should be included to the JSONPath specified as a key. |
| `content_type`required | `string` | Content type string |
| `sc_versions`required | `object` | Staircase version object |
| `sc_version_from`required | `integer` | Staircase version from |
| `sc_version_to`required | `integer` | Staircase version to |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Other responses
`204``422``500`
`GET` `/elements/{element_path}`
#### Retrieve Mappings for Element
`retrieveMapping`
Retrieve Mappings for Element retrieves a list of mappings across all available languages for the specified element.
##### Response
200400403
application/json Copy List of mappings
```
{
"lang-name": "$utils.split('$.address', ' ')[1]",
"lang-name2": "$.address"
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `element_path` required | `string` path | `%24.deal_sets%5B0%5D.collaterals%5B0%5D.address.city` | (*URLEncoded*)[] JSONPath to element is Staircase language |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Other responses
`200`
`GET` `/lexicon`
#### Retrieve Single Staircase Lexicon
`retrieveSingleStaircaseLexicon`
Retrieve Single Staircase Lexicon retrieves a Staircase lexicon name, mapping, and content type.
A lexicon translates between Staircase language versions, and is internally named VX_TO_VY - where X is lower, Y is higher version. FromPath and ToPath definitions are defined by sc_version_from and sc_version_to in lexicon definition.
Example: Lexicon: V0_TO_V2
Lexicon writer initially writes a lexicon from V0 to V2 - in this case sc_version_from = 0, sc_version_to = 2. Later, wants to add detail, etc. and defines lexicon from V2 to V0. In this case, new lexicon overwrites existing one with same name: V0_TO_V2 - in this case, however, internal definition shows sc_version_from = 2 and sc_version_to = 0.
During runtime, incoming payload indicates sc_version_from and sc_version_to. Forward translation is done if versions match, reverse translation otherwise.
When retrieving Lexicon - must pay close attention to directionality contained within language definition to determine how lexicon was originally written.
##### Response
200400403404
application/json Copy Language
```
{
"name": "string",
"mapping": {
"$.foo": "$.bar",
"$.biz": "$.baz"
},
"mapping_info": {
"language_elements": {
"coverage": "string",
"mapped_count": 0,
"unmapped_count": 0,
"unmapped": [
"string"
]
},
"staircase_elements": {
"coverage": "string",
"mapped_count": 0,
"unmapped_count": 0,
"unmapped": [
"string"
]
}
},
"values_mapping": [
{
"element": "string",
"mapping": [
{
"staircase_value": "string",
"language_value": "string"
}
]
}
],
"required_fields": {
"language_elements": [
"string"
],
"staircase_elements": [
"string"
]
},
"sc_versions": {
"sc_version_from": 0,
"sc_version_to": 1
},
"content_type": "application/json"
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sc_version_from` required | `integer` query | `2` | Staircase version from |
| `sc_version_to` required | `integer` query | `2` | Staircase version to |
##### Response `200``application/json`
7 fields
Language
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Name |
| `mapping` | `object` | Mapping object |
| `mapping_info` | `object` | Mapping info object |
| `language_elements` | `object` | Mapping info object - language elements |
| `coverage` | `string` | Element coverage |
| `mapped_count` | `number` | Element mapped count |
| `unmapped_count` | `number` | Element unmapped count |
| `unmapped` | `string[]` | Element unmapped array |
| `staircase_elements` | `object` | Staircase element object |
| `coverage`required | `string` | Element coverage |
| `mapped_count`required | `number` | Element mapped count |
| `unmapped_count`required | `number` | Element unmapped count |
| `unmapped`required | `string[]` | Element unmapped array |
| `values_mapping` | `object[]` | Value mapping array |
| `element`required | `string` | Value mapping element |
| `mapping` | `object[]` | Value mapping element |
| `staircase_value` | `string` | Value mapping staircase value |
| `language_value` | `string` | Value mapping language value |
| `required_fields` | `object` | Required fields object |
| `language_elements`required | `string[]` | Language's elements array |
| `staircase_elements`required | `string[]` | Staircase's elements array |
| `sc_versions` | `object` | Staircase version |
| `sc_version_from`required | `integer` | Staircase version from |
| `sc_version_to`required | `integer` | Staircase version to |
| `content_type` | `string` | Content type |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`422`
### Monitoring Dashboard
`GET` `/dashboard/configurations`
#### Get Dashboard Configurations
`getDashboardConfigurations`
**Retrieve registered dashboard configurations.
##### Response
400403404
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Response `200``application/json`
3 fields
Configurations retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `health_key` | `string` | Environment health key. |
| `host_environment` | `string` | Environment domain name. |
| `config_type` | `string` | Dashboard configuration type. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`PUT` `/dashboard/configurations`
#### Create Dashboard Configuration
`createDashboardConfiguration`
The primary function of this service is to facilitate the configuration of a dashboard that is specifically designed to monitor language products within a specified environment. The data required for monitoring will be retrieved through the utilization of a Health key and the information obtained will be presented using the Console product. For further clarification on the practical application of this service, kindly refer to the views that are maintained by the Language team. It should be noted that data will be fetched on a daily basis, with the worker commencing at precisely 07:00 am (UTC).
##### Request
application/json Copy
```
{
"health_key": "health-key",
"host_environment": "lang.staircaseapi.com"
}
```
##### Response
201400403404422
application/json Copy Configuration response
```
{
"message": "Configuration created."
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
```
{
"message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `host_environment`required | `string` | Environment domain name. |
| `health_key`required | `string` | Health key. |
##### Response `201``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `422``application/json`
1 fields
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
`DELETE` `/dashboard/configurations/{host_environment}`
#### Delete Dashboard Configuration
`deleteDashboardConfiguration`
This service removes configuration.
##### Response
200403404
application/json Copy Configuration response
```
{
"message": "Configuration deleted."
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `host_environment` required | `string` path | `lang.staircaseapi.com` | Environment domain name |
##### Response `200``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### EMR
`POST` `/emr`
#### Start EMR Translation
`startEMRTranslation`
Start new EMR translation
##### Request
application/json Copy
```
{
"input_bucket_name": "foo",
"input_path": "data",
"output_bucket_name": "bar",
"from_language": "my_lang",
"to_language": "lexicon"
}
```
##### Response
200400404
application/json Copy Successfully started the translation.
```
{
"product_id": "test_product",
"status": "operational"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Request body`application/json`
8 fields
| Field | Type | Description |
| --- | --- | --- |
| `input_bucket_name`required | `string` | Bucket name where to take the input data from. |
| `input_path`required | `string` | Prefix to data in the input bucket. |
| `input_schema` | `object[]` | Fields names and datatypes. |
| `Name` | `string` | Field name. |
| `Type` | `string` | Field datatype.`bigint``boolean``double``string` |
| `output_bucket_name` | `string` | Bucket name where to put the output data. Optional if datalake_name is provided. |
| `from_language`required | `string` | Language to translate from. |
| `to_language`required | `string` | Language to translate to. |
| `datalake_name` | `string` | Mortgage data lake to use. Will be used to define output s3-location, tables for entities unification, and columns for output tables to save. |
| `callback_url` | `string` | If specified, the URL will be called when Job is finished. We will send POST request to the URL with jobRunId, state and stateDetails in the request body as JSON. |
##### Response `200``application/json`
3 fields
Successfully started the translation.
| Field | Type | Description |
| --- | --- | --- |
| `applicationId`required | `string` | applicationId |
| `jobRunId`required | `string` | jobRunId |
| `arn`required | `string` | arn |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/fake`
#### FakeEMR
`FooBar`
Fake
foo
##### Response
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`204`
`GET` `/emr/{job_id}`
#### Get EMR Translation status
`getEMRTranslation`
EMR translation status
##### Response
200404
application/json Copy Data about the EMR translation
```
{
"product_id": "test_product",
"status": "operational"
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string` path | `00fdj7a1e1ai000a` | Job ID |
##### Response `200``application/json`
6 fields
Data about the EMR translation
| Field | Type | Description |
| --- | --- | --- |
| `applicationId`required | `string` | ID of app |
| `jobRunId`required | `string` | ID of current Job run |
| `createdAt`required | `string` | Creation time of the job |
| `updatedAt`required | `string` | Last update time of the job |
| `state`required | `string` | Current state of the job |
| `stateDetails`required | `string` | Details of the current state |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### MDL
`POST` `/etl/jobs`
#### Start MDL ETL JOB
`startMDLETLJob`
##### Request
application/json Copy
```
{
"year": 2022,
"month": 1,
"day": 1,
"datalake_name": "datalake"
}
```
##### Response
200400404
application/json Copy Successfully started the translation.
```
{
"executionArn": "123"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Container not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `year` | `integer` | YearExample `2022` |
| `month` | `integer` | MonthExample `1` |
| `day` | `integer` | DayExample `1` |
| `datalake_name` | `string` | Datalake NameExample `datalake` |
##### Response `200``application/json`
1 fields
Successfully started the translation.
| Field | Type | Description |
| --- | --- | --- |
| `executionArn`required | `string` | executionArn |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Missing API key
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Languages
`PUT` `/languages/{language_name}`
#### Create or Update Language
`updateLanguage`
Create or Update Language replaces mappings for a specified language. All previously created mappings are removed, and new mappings are created. If a language with the specified name doesn't exist, this service will create it. In general, languages are either pre-built and stored in GitHub, or built directly by a customer. They can be in either .csv or .json format.
Guide for building a .csv-based language
Show the rest Guide for building a .json-based language
Retrieve a pre-built language to understand how they are constructed.
If the language is given in .csv format, which is more straightforward and can be built by a business analyst, Translator converts the .csv file into the more technical .json format.
#### JSONPath syntax
| JSONPath | Description |
| --- | --- |
| $ | the root object/element |
| @ | the current object/element |
| `. or []` | child operator |
| `..` | recursive descent. JSONPath borrows this syntax from E4X. |
| * | wildcard. All objects/elements regardless their names |
| [] | subscript operator. XPath uses it to iterate over element collections and for predicates. In JavaScript and JSON it is the native array operator. |
| [,] | Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set. |
| [start:end:step] | array slice operator borrowed from ES4. |
| ? | applies a filter (script) expression. |
| | script expression, using the underlying script engine. |
More info and examples can be found here
Also, you can specify constant values instead of JSONPath, for example:
```
{
"name": "new_language",
"mapping": {
"$.value": "Some constant value"
}
}
```
Sometimes, you might need to set dyanmic JSONPath, that will be generated based on data, that you have passed, for this purpose you can use `{{ }}` syntax, so `` will be executed first against your data, f.e you create language like this:
```
{
"mapping": {
"$.foo": "$.data.{{ $.target_field }}"
}
}
```
So when translation begins, `$.target_field` will be queried, and result of this query will replace `{{ $.target_field }}`.
For next input:
```
{
"target_field": "bar",
"data": {
"bar": "baz"
}
}
```
You will get next result:
```
{
"foo": "baz"
}
```
You may also need to set up a mapping to only happen in a single direction. For example, only when translating to staircase or from staircase. In order to do this place the mapping into the appropriate section in "single_direction_mappings". The mapping itself should look the same.
```
{
"single_direction_mappings": {
"to_staircase": {
"$.foo_only_to": "$.data.{{ $.target_field }}"
},
"from_staircase": {
"$.foo_only_from": "$.data.{{ $.target_field }}"
}
}
}
```
Lastly you may want to pre-process your data before translation or post-process after translation. This is possible by setting up hooks. In order to use hooks you will need to create endpoints inside of your staircase environment and then link the paths to those endpoints in the mapping hooks property. For example, if your environment is you will set up an endpoint at and then set mapping_hooks to {"pre": "my/pre/hook"}. The domain will be added automatically. The pre hook will be sent the exact request payload that was sent to the "/translate" endpoint. The post hook will be sent the translated data as json with the result under the key "translation_result".
```
{
"mapping_hooks": {
"pre": "my/pre/hook",
"post": "my/post/hook"
}
}
```
Also, we have some predefined `utils` that we can use in our mappings, just using `$utils.(*args)`
List of currently supported utils:
#### Join many elements to one string
`$utils.join([*elements], character)`
| Attribute | Type | Description |
| --- | --- | --- |
| elements | list of JSONPaths or constants | List of JSONPaths or constants, to elements to be joined |
| character | string | Character for join provided elements |
Note: Constants are items not starting with $ - are joined as-is.
Return value: Joined string
Example:
```
{
"name": "util_language",
"mapping": {
"$utils.join(['$.address.line_text', '$.address.city', '$.address.state_code', '$.postal_code', 'USA'], ' ')": "$.address"
}
}
```
#### Split one element to many
`$utils.split(element, separator)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element that should be split |
| separator | string | separator |
Return value: array of string
Example:
```
{
"name": "util_language",
"mapping": {
"$.deal_sets[0].collaterals[0].address.line_text": "$utils.split('$.address', ' ')[0]",
"$.deal_sets[0].collaterals[0].address.city": "$utils.split('$.address', ' ')[1]",
"$.deal_sets[0].collaterals[0].address.state_code": "$utils.split('$.address', ' ')[2]",
"$.deal_sets[0].collaterals[0].address.postal_code": "$utils.split('$.address', ' ')[3]"
}
}
```
#### Slice String
`$utils.slice(element, beginIndex, endIndex)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element to be sliced |
| beginIndex | number | The zero-based index at which to begin extraction. |
| endIndex | number | The zero-based index before which to end extraction. The character at this index will not be included. |
#### Use first element that has a value defined
`$utils.first_defined(elements)`
| Attribute | Type | Description |
| --- | --- | --- |
| elements | list of JSONPathes | List of JSONPathes to elements, each path will be checked in order of list to find the first defined |
Return value: value of first defined element or null
Example:
```
{
"name": "util_language",
"mapping": {
"$.name": "$utils.first_defined(['$.official_name', '$.first_name', '$.nickname'])",
}
}
```
#### String
`$utils.if_value_in(element, values)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element, the value of this element will be checked against the values list |
| values | list of strings | List of values deemed to be valid, if the element doesn't match any values it will return null |
Return value: value of element if it's deemed valid or null
Example:
```
{
"name": "util_language",
"mapping": {
"$.deal_type": "$utils.if_value_in('$.type', ['type_a', 'type_b', 'type_c'])"
}
}
```
#### Transform values
Specify `values_mapping` to transform values. Example:
Use the keyword default for no match. Note: Feature is useful for one-way mapping - use caution when reverse-mapping from staircase back to language.
```
{
"name": "values_mapping_language",
"values_mapping": [
{
"element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
"mapping": [
{"staircase_value": "HelloWorld", "language_value": "FooBar"},
{"staircase_value": "BarBaz", "language_value": "WorldHello"},
{"staircase_value": "CatchAll", "language_value": "_default_"},
],
}
]
}
```
Where element is JSONPath in staircase language, and mapping is list of values mapping for specified element
#### Date handling
Specify `normalize_date` to transform dates into standard yyyy-MM-dd format or `denormalize_date` to transform dates from this format.
```
{
"mapping": {},
"single_direction_mappings": {
"to_staircase": {
"$.borrower_birth_date": "$utils.normalize_date('$.birthday', 'yyyy/MM/dd')"
},
"from_staircase": {
"$utils.denormalize_date('$.borrower_birth_date', 'yyyy/MM/dd')": "$.birthday"
}
}
}
```
Date to be in in standard ISO: year: yyyy, month: MM, day: dd, hour: hh, hour24:HH, minute: mm, second: ss, ms: SSS etc. If it is a timestamp, specify "epoch" for date_format argument If it should parsed from any format (for normalize_date), specify "any" for date_format argument
Letters T, Z and UTC to be stripped out prior to conversion.
Example: yyyy-MM-dd HH:mm:ss.SSS for 2019-01-02T15:26:02.123Z UTC
#### DateTime handling
Specify `normalize_datetime` to transform dates/times into standard yyyy-MM-ddTHH.mm.ss.SSS-0X:00 format or `denormalize_datetime` to transform dates/times from this format.
```
{
"mapping": {},
"single_direction_mappings": {
"to_staircase": {
"$.sample_datetime_field": "$utils.normalize_datetime('$.datetime_in', 'yyyy-MM-dd HH:mm:ss.SSS', 'UTC', 'ET')",
"$.sample_datetime_field2": "$utils.normalize_datetime('$.datetime_in_epoch', 'epoch', 'UTC', 'ET')"
},
"from_staircase": {
"$utils.denormalize_datetime('$.sample_datetime_field', 'yyyy-MM-dd HH:mm:ss.SSS', 'ET', 'UTC')": "$.datetime_in"
"$utils.denormalize_datetime('$.sample_datetime_field2', 'epoch', 'ET', 'UTC')": "$.datetime_in_epoch"
}
}
}
```
$utils.normalize_datetime(target_field, input_datetime_format, fromTimezone, toTimezone) $utils.denormalize_datetime(target_field, output_datetime_format, fromTimezone, toTimezone)
Date to be in in standard ISO or epoch If it should parsed from any format, specify "any" for input_datetime_format/output_datetime_format argument fromTimezone and toTimezone must be specified as "UTC","ET","CT","PT" Daylight Savings Time is calcuated based on target date, and will be returned based on target date
year: yyyy, month: MM, day: dd, hour: hh, hour24:HH, minute: mm, second: ss, ms: SSS etc.
Output date/time in ISO standard: yyyy-MM-ddTHH:mm:ss.SSS-0X:00 X = offset from UTC (i.e. 5 for EST / 4 for EDT)
Example: ('$.datetime_in', 'yyyy-MM-dd HH:mm:ss.SSS','UTC','ET') - converts from UTC to ET Example: ($.datetime_in_epoch', 'epoch','UTC','ET') - converts from epoch - in UTC by definition - to ET
#### Parse Float
Specify `parse_float` to transform floats into standard format. Second value - number of digits past decimal.
```
{
"name": "util_language",
"mapping": {
"$.float_value_result": "$utils.parse_float('$.float_value_input', '2')"
},
}
```
to use with wildcards:
```
{
"name": "util_language",
"mapping": {
"$.deal_sets.deal_set[0].deals.deal[0].assets.asset[*].cash_or_market_value_amount": "$utils.map(\'$.report.items[0].accounts[*].balances.current\',\'$utils.parse_float(item,2)\')"
},
}
```
note: item is a keyword - and must be used as-is
Parses float and trims digits past decimal to integer given - rounds as appropriate. Incoming float values can come in as either string ("234.556") or float (234.556). Outgoing values are numeric only. JSON does not differentiate between integer and float, as such, trailing zeros are trimmed. If a float is un-translatable, will be returned as null/None.
Examples:
| Input | DigitsPastDecimal | Result |
| --- | --- | --- |
| 234.567 | 2 | 234.57 |
| Foobaar | 2 | None |
| 234.567 | 6 | 234.567 |
| 234 | 6 | 234 |
#### Sum Numbers
Specify `sum_numbers` to sum numbers and truncate/round as above.
```
{
"name": "util_language",
"mapping": {
"$.sum_numbers_result": "$utils.sum_numbers('$.sum_number_in';'$.sum_number_in2';'sum_number_in3', '2')"
},
}
```
Items are truncated/rounded prior to summation. Final sum is also truncated/rounded as specified.
#### Multiply Numbers
Specify `multiply_numbers` to multiply numbers and truncate/round as above.
```
{
"name": "util_language",
"mapping": {
"$.multiply_numbers_result": "$utils.multiply_numbers('$.number_in';12, '2')"
},
}
```
Items are truncated/rounded prior to summation. Final sum is also truncated/rounded as specified.
#### Parse location
You can parse street address and street intersection for the United States. Util knows about directional prefixes and suffixes, fractional building numbers, building units, grid-based addresses (such as those used in parts of Utah), 5 and 9 digit ZIP codes, and all of the official USPS abbreviations for street types, state names and secondary unit designators.
`$utils.parse_location(element)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | valid JSONPathes | JSONPath to the element, that should be parsed |
Return value:
```
{
"title": "Address"
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "House or street number."
},
"prefix": {
"type": "string",
"description": "Directional prefix for the street, such as N, NE, E, etc. A given prefix should be one to two characters long."
},
"street": {
"type": "string",
"description": "Name of the street, without directional or type qualifiers."
},
"type": {
"type": "string",
"description": "Abbreviated street type, e.g. Rd, St, Ave, etc. See the USPS official type abbreviations at for a list of abbreviations used."
},
"suffix": {
"type": "string",
"description": "Directional suffix for the street, as above."
},
"city": {
"type": "string",
"description": "Name of the city, town, or other locale that the address is situated in."
},
"state": {
"type": "string",
"description": "The state which the address is situated in, given as its two-letter postal abbreviation. for a list of abbreviations used."
},
"zip": {
"type": "string",
"description": "Five digit ZIP postal code for the address, including leading zero, if needed."
},
"sec_unit_type": {
"type": "string",
"description": "If the address includes a Secondary Unit Designator, such as a room, suite or appartment, the sec_unit_type field will indicate the type of unit."
},
"sec_unit_num": {
"type": "string",
"description": "If the address includes a Secondary Unit Designator, such as a room, suite or appartment, the sec_unit_num field will indicate the number of the unit (which may not be numeric)."
}
}
}
```
None of his properties is guaranteed and depends on adress that is provided
###### Example:
```
{
"mapping": {
"$.number": "$utils.parse_location('$.address')['number']",
"$.city_state": "$utils.join([$utils.parse_location('$.address')['city'], $utils.parse_location('$.address')['state']], ' ')"
},
"name": "address_location"
}
```
#### SetNull
Specify `set_null` to hardcode a null to the field - will show in JSON as 'None'. Cannot be used with wildcards.
###### Example:
```
{
"name": "util_language",
"mapping": {
"$.null_value_to": "set_null",
"set_null": "$.null_value_from"
},
}
```
#### Generate ID
You have ability to generate ULID by using `$utlis.ulid`
`$utils.ulid(element, many)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath in your payload, it can point to anything (object, array, string, etc.), if during translation value, that will be result for two usage of this util will be the same, than it will generate same ids |
| many | boolean | Indicate, if provided element points to array, generate one ids, based on the whole array, or id for every array element |
###### Example:
###### Language:
```
{
"mapping": {
"$.elements[*].id": "$utils.ulid('$.input[*].foo')",
"$.data[*].id": "$utils.ulid('$.input[*].bar')"
}
}
```
###### Input:
```
{
"foo": [1, 2, "hello"],
"bar": [1, 2, "hello"]
}
```
###### Output:
```
{
"elements": [
{"id": "01F4EYZ82K7M46DQAZKZT4Y7QT"},
{"id": "01F4EYZVVM3BTAYHBHV1AJDQZC"},
{"id": "01F4EZ05VWZZ3BM3EFP6FYQ28H"}
],
"data": [
{"id": "01F4EYZ82K7M46DQAZKZT4Y7QT"},
{"id": "01F4EYZVVM3BTAYHBHV1AJDQZC"},
{"id": "01F4EZ05VWZZ3BM3EFP6FYQ28H"}
]
}
```
As you can see, we generated id's, but we have same id's in `elements` and `data` arrays, because input contains same values in objects by provided in language JSONPathes
#### Frame
If your languge is in `application/ld+json` you can apply frame algorithm to your payload, and query data from it
`$utils.frame(element, frameObject)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath for querying framed payload |
| frameObject | object | JSON-LD frame |
Language example:
```
{
"mapping": {
"$.book_title": "$utils.frame('$[\'ex:contains\'][\'dc11:title\']', { '@type': 'ex:Library', 'ex:contains': { '@type': 'ex:Book' } })"
},
"jsonld_context": {
"dc11": "",
"ex": "",
"xsd": "",
"ex:contains": {
"@type": "@id"
}
},
"content_type": "application/ld+json"
}
```
Input:
```
{
"@graph": [
{
"@id": "",
"@type": "ex:Library",
"ex:contains": ""
},
{
"@id": "",
"@type": "ex:Book",
"dc11:creator": "Plato",
"dc11:title": "The Republic",
"ex:contains": ""
},
{
"@id": "",
"@type": "ex:Chapter",
"dc11:description": "An introductory chapter on The Republic.",
"dc11:title": "The Introduction"
}
]
}
```
Output:
```
{
"book_title": "The Republic"
}
```
#### Convert string case
`$utils.convert_case(element, case)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be converted |
| case | string | Supported conversions: upper, lower |
Return value: Converted string
Example:
```
{
"name": "util_language",
"mapping": {
"$utils.convert_case('$.address.state_code', 'upper')": "$.state"
}
}
```
#### Extract text with regex
`$utils.regex_extract(element, regex)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be extracted from |
| regex | regex | The regex to use for extracting text from the element |
Return value: Extracted string
Example:
```
{
"name": "regex_language",
"mapping": {
"$.income": "$utils.regex_extract('$.borrower_income', '\\d+')"
}
}
```
#### Set current date
`$utils.set_current_date`
Example:
```
{
"name": "current_date_language",
"mapping": {
"$.current_date": "$utils.set_current_date"
}
}
```
Return value: string with current date in normalized format "yyyy-MM-dd" by 'America/New_York' timezone.
#### Format field
`$utils.format(element, type)`
| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be extracted from |
| type | string | Type of formatting to produce. Choices are "ssn", "itin", "percent", "phone_number", "phone_number_parentheses" |
Return value: Formatted string
Example:
```
{
"name": "format-ssn",
"mapping": {
"$.ssn": "$utils.format('$.incoming_ssn', 'ssn')"
}
}
```
#### Relationship
`$utils.relationship(element, query, key, relName)`
Map XLINK relationships (`1:1` and `1:M`) used in XML-like schemas
| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to extract first relationship entity |
| query | JSONPath | JSONPath to extract the second relationship entity |
| key | JSONPath | JSONPath of key that contains the value of first relationship component |
| relName | string | Name to be used for relationship in output object |
The following is an example mapping (note: mappings for this operation are single-direction):
```
{
"single_direction_mappings": {
"to_staircase": {
"$.relationships.relationship[*]|ASSET_LIABILITY-$.assets[?(@.@type=='real_estate_owned')]-with_liability[*]": "$utils.relationship('$.assets[?(@.@type==\'real_estate_owned\')]', 'with_liability[*]', '@id', 'ASSET_LIABILITY')"
}
}
}
```
The above mapping uses the JSON Path query `$.assets[?(@.@type==\'real_estate_owned\')]` to get the relationship's left-side (or from-) entity. The value in its `@id` field will be use to mark this first entity in the created output. The JSON Path `with_liability[*]` marks the value of right-side (or to-) entity in the relationship. The relationship's name is
```
{
"people": [
{
"@id": "BORROWER_1",
"@type": "borrower",
"owns_asset": [
"ASSET_1",
"ASSET_2"
]
}
],
"assets": [
{
"@id": "ASSET_1",
"@type": "retirement_account",
"has_account_identifier": {
"has_value": "4444"
},
"has_asset_description": {
"has_value": "Roth IRA"
},
"has_market_value_amount": {
"has_value": 923.27
}
},
{
"@id": "ASSET_2",
"@type": "real_estate_owned",
"has_market_value_amount": {
"has_value": 25632.87
},
"with_liability": [
"LIABILITY_1"
]
}
],
"liabilities": [
{
"@id": "LIABILITY_1",
"@type": "liability",
"has_liability_payment_amount": {
"has_value": 923.27
}
}
]
}
```
When the language mappings are applied to the above example input, the following output is created:
```
{
"relationships": {
"relationship": [
{
"relationship_link": "ASSET_LIABILITY",
"link_from": "ASSET_2",
"link_to": "LIABILITY_1"
}
]
}
}
```
##### Request
Example with utilsXML Language exampleExample with values mapping
application/json Copy
```
{
"mapping": {
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate",
"$utils.join(['$.deal_sets[0].collaterals[0].address.line_text', '$.deal_sets[0].collaterals[0].address.city', '$.deal_sets[0].collaterals[0].address.state_code', '$.deal_sets[0].collaterals[0].address.postal_code'], ' ')": "$.address",
"$.deal_sets[0].collaterals[0].address.line_text": "$utils.split('$.address', ' ')[0]",
"$.deal_sets[0].collaterals[0].address.city": "$utils.split('$.address', ' ')[1]",
"$.deal_sets[0].collaterals[0].address.state_code": "$utils.split('$.address', ' ')[2]",
"$.deal_sets[0].collaterals[0].address.postal_code": "$utils.split('$.address', ' ')[3]"
},
"sc_version": 0
}
```
application/json Copy
```
{
"content_type": "application/xml",
"mapping": {
"$.about_versions.about_version_identifier": "$.MESSAGE[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].AboutVersionIdentifier[0]._text[0]",
"$.about_versions.data_version_identifier": "$.MESSAGE[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].DataVersionIdentifier[0]._text[0]",
"$.deal_sets[*].about_versions.data_version_identifier": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].DataVersionName[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.address.address_line_text": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].AddressLineText[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.address.city_name": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].CityName[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.address.postal_code": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].PostalCode[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.address.state_code": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].StateCode[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.attachment_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].AttachmentType[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.construction_method_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].ConstructionMethodType[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.financed_unit_count": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].FinancedUnitCount[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_estate_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyEstateType[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_estimated_value_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyEstimatedValueAmount[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_existing_clean_energy_lien_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyExistingCleanEnergyLienIndicator[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_in_project_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyInProjectIndicator[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_mixed_usage_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyMixedUsageIndicator[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.property_usage_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyUsageType[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_detail.pud_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PUDIndicator[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_valuations[*].property_valuation_detail.appraisal_identifier": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_VALUATIONS[0].PROPERTY_VALUATION[*].PROPERTY_VALUATION_DETAIL[0].AppraisalIdentifier[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.property_valuations[*].property_valuation_detail.property_valuation_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_VALUATIONS[0].PROPERTY_VALUATION[*].PROPERTY_VALUATION_DETAIL[0].PropertyValuationAmount[0]._text[0]",
"$.deal_sets[*].collaterals[*].subject_property.sales_contracts[*].sales_contract_detail.sales_contract_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].SALES_CONTRACTS[0].SALES_CONTRACT[*].SALES_CONTRACT_DETAIL[0].SalesContractAmount[0]._text[0]"
}
}
```
application/json Copy
```
{
"mapping": {
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate"
},
"values_mapping": [
{
"element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
"mapping": [
{
"language_value": "FooBar",
"staircase_value": "HelloWorld"
},
{
"language_value": "WorldHello",
"staircase_value": "BarBaz"
}
]
}
],
"sc_version": 0
}
```
##### Response
202400403
application/json Copy Async update accepted
```
Async update accepted
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
6
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | Language name |
| `validate` | `boolean` query | `true` | Whether to validate the language before inserting. By default it will be validated. |
| `sc_version` | `integer` query | `1` | Version of the staircase language to which this language targets (.csv only) |
| `payload_content_type` | `string` query | `application/json` | Content type of payload - defaults to application/json (.csv only) |
| `async` | `boolean` query | `true` | Whether to execute the update asynchronously, this is best for larger operations. Be default, async is off. Use the retrieve language update status endpoint to check status and the retrieve language endpoint to get the updated language. |
| `parse_enum_values_types` | `boolean` query | `true` | if enum values should be parsed with datatypes (booleans, integers, floats), set this parameter to true. |
##### Request body`application/json`
10 fields
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Language name |
| `mapping`required | `object` | Mapping |
| `single_direction_mappings` | `object` | Single direction mappings |
| `values_mapping` | `object[]` | Mapping values |
| `element`required | `string` | Element |
| `mapping`required | `object[]` | Mapping |
| `staircase_value`required | `string` | Staircase value |
| `language_value`required | `string` | Language value |
| `unique_arrays` | `object` | Key-value pairs, where key is JSONPath to array of objects, and value is key, that has been unique |
| `merge_arrays` | `object` | Key-value pairs, where key is JSONPath to array which will contain merged elements, and value is an array, which contains JSONPaths to arrays that should be excluded from result and all their elements should be included to the JSONPath specified as a key. |
| `content_type` | `string` | Content type`application/json``application/ld+json``application/xml` |
| `sc_version` | `integer` | Staircase version language is mapped to - defaults to 0 |
| `validate_paths` | `boolean` | Turn on or off the validation of language mapping paths. By default, turned on. |
| `async` | `boolean` | Whether to execute the update asynchronously, this is best for larger operations. Be default, async is off. Use the retrieve language update status endpoint to check status and the retrieve language endpoint to get the updated language. |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Other responses
`202``204``422`
`GET` `/languages/{language_name}/status`
#### Retrieve Language Update Status
`retrieveLanguageStatus`
Retrieve Language Update Status retrieves the status of an asynchronous language update.
##### Response
200400403404
application/json Copy Language
```
{
"status": "RUNNING"
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | Language name |
##### Response `200``application/json`
1 fields
Language
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Update in progress |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`DELETE` `/languages/{language_name}`
#### Delete Language
`deleteLanguage`
Delete Language removes a language from the translator.
##### Response
400403404
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | Language name |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`204`
`GET` `/languages/{language_name}/elements`
#### Retrieve Language Elements
`retrieveLanguageElements`
Retrieve Language Elements retrieves a list of Staircase elements present in a language.
##### Response
200400403404
application/json Copy List of staircase elements present in language
```
[
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range",
"$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value",
"$.deal_sets[0].collaterals[0].address.line_text",
"$.deal_sets[0].collaterals[0].address.city",
"$.deal_sets[0].collaterals[0].address.state_code",
"$.deal_sets[0].collaterals[0].address.postal_code"
]
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | Language name |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200`
`GET` `/languages`
#### Retrieve Languages
`retrieveLanguages`
Retrieve Languages returns a list of all supported languages on the platform.
Note: There is a maximum amount of languages returned in a response. If there are more languages left to retrieve, the next field in the response will contain the name of the last retrieved language. To retrieve the next set of languages, use the optional after_name query parameter.
Show the rest
```
curl --location --request GET '' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json'
```
```
"languages": [
{"name": "mismo34", "version": "3.4", "content_type": "application/ld+json"},
{"name": "jsonlang", "version": "0.1", "content_type": "application/json"},
{"name": "xmlang", "version": "0.1", "content_type": "text/xml"},
]
}
```
##### Response
400403
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `after_name` | `string` query | `mismo34` | name of the last language retrieved in the list |
| `limit` | `integer` query | `100` | number of items per page |
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `next` | `string` | Name of the last language evaluated (bookmark) |
| `languages` | `object[]` | Language name, version and type of content for the language mapping |
| `name` | `string` | Language name |
| `version` | `string` | Staircase language version |
| `content_type` | `string` | Type of content for the language mapping |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
`GET` `/languages/{language_name}`
#### Retrieve Single Language
`retrieveLanguage`
Retrieve Single Language retrieves a language name, mapping, and content type for a language. If the language is being updated asynchronously and the update hasn't finished the response will contain a status.
##### Response
200400403404
application/json Copy Language
```
{
"name": "my_lang",
"mapping_info": {
"language_elements": {
"coverage": "100%",
"unmapped_count": 0,
"mapped_count": 3,
"unmapped": []
},
"staircase_elements": {
"coverage": "100%",
"unmapped_count": 0,
"mapped_count": 4,
"unmapped": []
}
},
"mapping": {
"$.deal_sets.deal_set[0].deals.deal[0].assets.asset[*].account_identifier": "$.report.items[0].accounts[*].mask",
"$.deal_sets.deal_set[0].deals.deal[0].services.service[0].verification_of_assets.verification_of_assets_response.partner_product": "Assets",
"$.deal_sets.deal_set[0].deals.deal[0].services.service[0].verification_of_assets.verification_of_assets_response.service_date": "$utils.slice('$.report.date_generated', 0, 10)",
"$.document.extracted_data.fanniemae_or_freddiemac": "$.extractedData[?(@.name == 'Form_Name')].data"
},
"values_mapping": [
{
"mapping": [
{
"staircase_value": "Fannie Mae",
"language_value": "fanniemae"
},
{
"staircase_value": "Freddie Mac",
"language_value": "freddiemac"
}
],
"element": "$.document.extracted_data.fanniemae_or_freddiemac"
}
],
"sc_version": 0,
"content_type": "application/json"
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | Language name |
##### Response `200``application/json`
6 fields
Language
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | name |
| `mapping` | `object` | Mapping type either string or array |
| `mapping_info` | `object` | Meta information about existing mapping |
| `language_elements` | `object` | Meta information about existing mapping elements |
| `coverage` | `string` | Meta information about coverage |
| `mapped_count` | `number` | Meta information about mapped_count |
| `unmapped_count` | `number` | Meta information about unmapped_count |
| `unmapped` | `string[]` | Meta information about unmapped |
| `staircase_elements` | `object` | Meta information about staircase elements |
| `coverage` | `string` | Meta information about coverage |
| `mapped_count` | `number` | Meta information about mapped_count |
| `unmapped_count` | `number` | Meta information about unmapped_count |
| `unmapped` | `string[]` | Meta information about unmapped |
| `sc_version` | `integer` | Sc_version number |
| `values_mapping` | `object[]` | Array of values mapping |
| `element` | `string` | Element name |
| `mapping` | `object[]` | Mapping array |
| `staircase_value` | `string` | Staircase value |
| `language_value` | `string` | Language value |
| `content_type` | `string` | Type of content sent in the response`application/json``application/ld+json``application/xml` |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
### Mappings
`POST` `/mappings/{mapping_name}/import`
#### Create Mapping from Payload
`createMapping`
Create mapping from existing payload
Import mapping takes an existing payload and creates a starter mapping from it.
##### Request
application/json Copy
```
{
"settings": {
"auto-create": true
},
"data": {
"report": {
"asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
"client_report_id": "123abc",
"date_generated": "2020-06-05T22:47:53Z",
"days_requested": 3,
"items": [
{
"accounts": [
{
"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
"name": "Plaid Saving",
"official_name": "Plaid Silver Standard 0.1% Interest Saving"
}
]
}
],
"user": {
"client_user_id": "123456789",
"email": "accountholder0@example.com",
"first_name": "Alberta",
"last_name": "Charleson",
"middle_name": "Bobbeth",
"phone_number": "111-222-3333",
"ssn": "999-00-0000"
}
},
"request_id": "eYupqX1mZkEuQRx",
"warnings": []
}
}
```
##### Response
201400403
application/json Copy Mapping created successfully
```
{
"name": "mapping_name",
"mapping_info": {
"language_elements": {
"coverage": 0,
"mapped_count": 0,
"unmapped_count": 16,
"unmapped": [
"$.report.asset_report_id",
"$.report.client_report_id",
"$.report.date_generated",
"$.report.days_requested",
"$.report.items[*].accounts[*].account_id",
"$.report.items[*].accounts[*].name",
"$.report.items[*].accounts[*].official_name",
"$.report.user.client_user_id",
"$.report.user.email",
"$.report.user.first_name",
"$.report.user.last_name",
"$.report.user.middle_name",
"$.report.user.phone_number",
"$.report.user.ssn",
"$.request_id",
"$.warnings[*]"
]
},
"staircase_elements": {
"coverage": 0,
"mapped_count": 0,
"unmapped_count": 0,
"unmapped": null
}
},
"mapping": {
"": [
"$.report.asset_report_id",
"$.report.client_report_id",
"$.report.date_generated",
"$.report.days_requested",
"$.report.items[*].accounts[*].account_id",
"$.report.items[*].accounts[*].name",
"$.report.items[*].accounts[*].official_name",
"$.report.user.client_user_id",
"$.report.user.email",
"$.report.user.first_name",
"$.report.user.last_name",
"$.report.user.middle_name",
"$.report.user.phone_number",
"$.report.user.ssn",
"$.request_id",
"$.warnings[*]"
]
}
}
```
application/json Copy Unable to create mapping from payload
```
{
"message": "Unable to create mapping from payload"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `mapping_name` required | `string` path | `my_mapping` | Mapping name |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `settings` | `object` | Settings object |
| `auto-create` | `boolean` | Whether to save the mapping after importing it. Defaults to true. |
| `data` | `object` | Data object |
##### Response `400``application/json`
1 fields
Unable to create mapping from payload
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Other responses
`201`
### Rules Generator
`POST` `/rules-generator/jobs`
#### Generate Rules
`generateRules`
Generate Rules from one language to another. Currently supports mapping from/to:
- `lexicon`
- `staircase-graph`
- `staircase-mismo-limited`
Multiple algorithms are supported. The source of the partner language schema to match is the Lexicon Languages Registry.
List of algorithms:
- property_matching - The algorithm uses similarity between property and class names to generate rules. Good fit for more flat languages.
- containers_first_matching - The algorithm uses the similarity between class names in the first priority, and property names in the second, to generate rules. Good fit for more nested languages.
- gpt - The algorithm uses GPT-4 to generate rules.
There is also a possibility to select a string similarity algorithm and similarity score cutoff. These parameters define how particular containers and properties will be chosen as the best match to map in rules. The possible values for `similarity_algorithm` are ratio, jaro, and jaro_winkler:
Show the rest
- ratio (default) calculates the Levenshtein distance ratio of similarity between two sequences;
- jaro and jaro_winkler are string-edit distance algorithms that give more favorable ratings to strings that match from the beginning.
#### Parties Mapping
##### (works only for `containers_first_matching` algorithm)
In MISMO and MISMO-like languages, parties have a slightly different structure from staircase languages. In order to map parties from the partner language to the staircase you need to specify a path to value in the partner language that determines party type and corresponding value in the staircase language. Check the request body example for more details.
#### Static Mappings
##### (works only for `containers_first_matching` algorithm)
The rules-generation process consists of matching containers and end-properties:
- containers are objects and arrays.
- end-properties are literal values - strings, numbers, and booleans.
There are common cases when a partner language has similar end-properties to staircase language, but their container structure and names might be pretty different. The static mapping parameter solves this problem.
Static mappings are specialized for "hard-coding" the mappings only for containers, so the service is able to map properties (and child containers that are not specified in static mappings) between these containers by the similarity algorithm. Suppose some end-properties should be mapped although they don't match by similarity algorithm. In that case, the user should map it just manually by himself inside the generated rules sample after the generation.
Static mappings are specified in the `static_mappings` field of the `algorithm_settings` and might have a recursive structure with a `children` field for each mapping. `foreign_container` and `staircase_container` are relative paths (relative to the parent mapping, if it is in `children`) to the containers in the partner and staircase languages respectively. In staircase language it might be a v2 container in a root mapping, or a relationship in `children` mappings.
`foreign_container` might consist of a single node (like "role") or multiple nodes joined with a front slash (like "role/roles/roleDetail"). In this case, intermediate containers are treated as skipped in rules, so they will be mapped to the empty staircase path (`""`). The same logic might be applied by specifying `null` values for `staircase_container` & `staircase_type`.
So, these static mappings:
```
[
{
"foreign_container": "x/y/z",
"staircase_container": "assets",
"staircase_type": "asset"
}
]
```
are absolutely equal to these:
```
[
{
"foreign_container": "x",
"staircase_container": null,
"staircase_type": null
},
{
"foreign_container": "x/y",
"staircase_container": null,
"staircase_type": null
},
{
"foreign_container": "x/y/z",
"staircase_container": "assets",
"staircase_type": "asset"
}
]
```
and these:
```
[
},
{
"foreign_container": "x",
"staircase_container": null,
"staircase_type": null,
"children": [
{
"foreign_container": "y",
"staircase_container": null,
"staircase_type": null,
"children": [
{
"foreign_container": "z",
"staircase_container": "assets",
"staircase_type": "asset"
}
]
}
]
}
]
```
It might be useful to map different nested objects to the single item of the same staircase container & type:
```
[
{
"foreign_container": "ASSETS",
"staircase_container": "assets",
"staircase_type": "asset",
"children": [
{
"foreign_container": "ASSET/ASSET_DETAIL",
"staircase_container": null,
"staircase_type": null
}
]
]
}
]
```
In this case, all the properties of the `ASSETS` and the `ASSET_DETAIL` objects will be mapped to the same `asset` item.
If some foreign container is array and should be mapped to the staircase relationship, you should map exactly this array container to the relationship, and if needed, specify nested objects as `children`: For example, you have data like this:
```
{
"borrower": {
"name": "John Doe",
"some_dummy_node": {
"hmda_races": [
{
"hmda_races_info": {
"hmda_race_type": "bla-bla-bla"
},
"additional_info": {
"race_type_additional_description": "bla-bla-bla"
},
}
]
}
}
}
```
and you want to map `hmda_races` array to the `with_hmda_race` borrower's relationship. In this case, static mappings should look like this:
```
[
{
"foreign_container": "borrower/some_dummy_node/hmda_races",
"staircase_container": "with_hmda_race",
"staircase_type": "hmda_race",
"children": [
{
"foreign_container": "hmda_races_info",
"staircase_container": null,
"staircase_type": null
},
{
"foreign_container": "additional_info",
"staircase_container": null,
"staircase_type": null
}
]
}
]
```
##### More complete example
```
{
"algorithm_settings": {
"static_mappings": [
{
"foreign_container": "foreign_container_1",
"staircase_container": "staircase_container_1",
"staircase_type": "staircase_type_1",
"children": [
{
"foreign_container": "child_foreign_container_1",
"staircase_container": "child_staircase_container_1",
"staircase_type": "staircase_type_1_1",
"evaluate_separate": true,
"filter": {
"path": "filter_path_1",
"value": "filter_value_1",
"operation": "IS_EQUAL"
}
},
{
"foreign_container": "child_foreign_container_2",
"staircase_container": "child_staircase_container_2",
"staircase_type": "staircase_type_1_2"
}
]
},
{
"foreign_container": "foreign_container_2",
"staircase_container": "staircase_container_2",
"staircase_type": "staircase_type_2",
"evaluate_separate": true,
"filter": {
"path": "filter_path_3",
"value": true,
"operation": "IS_EQUAL"
}
}
]
}
}
```
##### Request
Property matching exampleContainer matching example with parties mappingContainer matching with static mappings
application/json Copy
```
{
"lang_from": "credit",
"lang_to": "staircase-graph",
"algorithm": "property_matching"
}
```
application/json Copy
```
{
"lang_from": "mismo-like",
"lang_to": "staircase-graph",
"algorithm": "container_first_matching",
"algorithm_settings": {
"parties_mapping": {
"path_to_type_value": "roles/roleDetail/partyRoleType",
"mappings": [
{
"foreign_type": "PARTY_ROLE_ENUM_BORROWER",
"staircase_type": "borrower"
},
{
"foreign_type": "PARTY_ROLE_ENUM_CO_BORROWER",
"staircase_type": "co_borrower"
},
{
"foreign_type": "PARTY_ROLE_ENUM_LOAN_ORIGINATOR",
"staircase_type": "loan_originator"
}
]
}
}
}
```
application/json Copy
```
{
"lang_from": "some_partner_lang",
"lang_to": "staircase-graph",
"algorithm": "container_first_matching",
"algorithm_settings": {
"static_mappings": [
{
"foreign_container": "foreign_container_1",
"staircase_container": "staircase_container_1",
"staircase_type": "staircase_type_1",
"children": [
{
"foreign_container": "child_foreign_container_1",
"staircase_container": "child_staircase_container_1",
"staircase_type": "staircase_type_1_1",
"evaluate_separate": true,
"filter": {
"path": "filter_path_1",
"value": "filter_value_1",
"operation": "IS_EQUAL"
}
},
{
"foreign_container": "child_foreign_container_2",
"staircase_container": "child_staircase_container_2",
"staircase_type": "staircase_type_1_2"
}
],
"evaluate_separate": false
},
{
"foreign_container": "foreign_container_2",
"staircase_container": "staircase_container_2",
"staircase_type": "staircase_type_2",
"evaluate_separate": true,
"filter": {
"path": "filter_path_3",
"value": true,
"operation": "IS_EQUAL"
}
}
]
}
}
```
##### Response
202400403404
application/json Copy Generated rules
```
{
"id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
"status": "running",
"lang_from": "staircase-graph",
"lang_to": "credit"
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `lang_from`required | `string` | Language to generate rules from |
| `lang_to`required | `string` | Language to generate rules to |
| `algorithm`required | `string` | Algorithm to use for generating rules`container_first_matching``gpt``property_matching` |
| `algorithm_settings` | `object` | Algorithm settings. |
| `similarity_algorithm` | `string` | The name of the similarity algorithm to use. The possible values are 'ratio', 'jaro', and 'jaro_winkler'. - 'ratio' (***default***) calculates the Levenshtein distance ratio of similarity between two sequences; - 'jaro' and 'jaro_winkler' are string-edit distance algorithms that give more favorable ratings to strings that match from the beginning.`jaro``jaro_winkler``ratio` |
| `score_cutoff` | `number (float)` | The minimum score a pair must have to be considered a match. This is based on the similarity measure provided by the selected algorithm. It represents the minimum allowed similarity score between two strings for them to be considered a match. |
| `override_container_names` | `object[]` | Array of objects with container names to override. |
| `staircase_type`required | `string` | `@type` for which container name should be overridden. |
| `staircase_container`required | `string` | Container name in staircase language to set always. |
| `parties_mapping` | `object` | Parties mapping settings. Required for container_first_matching algorithm. |
| `path_to_type_value` | `string` | Relative path starting from parties(case insensitive container) to value in partner language that determines party type. |
| `mappings` | `object[]` | Array of mappings from partner language party type to staircase language party type. |
| `foreign_type` | `string` | Party type in partner language. |
| `staircase_type` | `string` | Party type in staircase language. |
| `static_mappings` | `object[]` | Static mappings are specified to hard-code the mappings only for containers with container_first_matching algorithm. Can have a recursive structure with 'children' field for each mapping. |
| `foreign_container`required | `string` | The identifier of the foreign container that needs to be mapped. Might have multiple nodes separated by '/'. |
| `staircase_container`required | `string` | The identifier of the staircase container to which the foreign container is mapped. Might have multiple nodes separated by '/'. |
| `staircase_type`required | `string` | The type of the staircase container. |
| `children` | `object[]` | The array of child static mappings, allowing for recursive mapping structures. |
| `evaluate_separate` | `boolean` | A boolean flag indicating whether to evaluate the mapping separately. |
| `filter` | `object` | An object that specifies the filter conditions for the mapping for the direction `Foreign -> Staircase`. |
| `path` | `string` | The path to the property in the container that needs to be filtered. |
| `value` | `one of` | The value against which the property at the given path will be checked. |
| `operation` | `string` | The operation to be performed for filtering. Currently, only 'IS_EQUAL' operation is supported.`IS_EQUAL` |
##### Response `202``application/json`
2 fields
Generated rules
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Generation id |
| `status`required | `string` | Generation status`running` |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`GET` `/rules-generator/jobs/{id}`
#### Get Rules Generation Status
`getRulesGenerationStatus`
##### Response
200 Running200 Failed200 Completed400403404
application/json Copy Rules Generation Status
```
{
"id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
"status": "running",
"lang_from": "staircase-graph",
"lang_to": "credit",
"errors": null,
"rules": null,
"statistics": null
}
```
application/json Copy Rules Generation Status
```
{
"id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
"status": "failed",
"lang_from": "staircase-graph",
"lang_to": "credit",
"errors": [
"Error message 1",
"Error message 2"
],
"rules": null,
"statistics": null
}
```
application/json Copy Rules Generation Status
```
{
"id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
"status": "completed",
"lang_from": "staircase-graph",
"lang_to": "credit",
"errors": null,
"statistics": {
"mapped_properties_count": 3,
"unmapped_properties_count": 1,
"coverage_ratio": 0.75,
"unmapped_properties": [
"MESSAGE/DEAL_SETS/PARTIES/PARTY/ROLES/ROLE/PARTY_ROLE_IDENTIFIERS/PARTY_ROLE_IDENTIFIER/PartyRoleIdentifier"
],
"mapped_properties": [
{
"from": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS/ABOUT_VERSION/@SequenceNumber",
"to": "data_versions/has_sequence_number/has_value"
},
{
"from": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS/ABOUT_VERSION/DataVersionName",
"to": "data_versions/has_data_version_name/has_value"
},
{
"from": "MESSAGE/DEAL_SETS/PARTIES/PARTY/LEGAL_ENTITY/LEGAL_ENTITY_DETAIL/FullName",
"to": "organizations/has_organization_name/has_value"
}
]
},
"rules": [
{
"definition": {
"from": {
"path": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS"
},
"to": {
"path": "data_versions"
},
"attribute_mappings": [
{
"from": {
"value": "data_version"
},
"to": {
"path": "@type"
}
},
{
"from": {
"path": "ABOUT_VERSION"
},
"to": {
"path": ""
},
"attribute_mappings": [
{
"from": {
"path": "@SequenceNumber"
},
"to": {
"path": "has_sequence_number/has_value"
}
},
{
"from": {
"path": "DataVersionName"
},
"to": {
"path": "has_data_version_name/has_value"
}
}
]
}
]
}
},
{
"definition": {
"from": {
"path": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/PARTIES/PARTY",
"filter": {
"path": "ROLES/ROLE/ROLE_DETAIL/PartyRoleType",
"IS_EQUAL": "NotePayTo"
}
},
"to": {
"path": "organizations"
},
"attribute_mappings": [
{
"from": {
"value": "note_pay_to"
},
"to": {
"path": "@type"
}
},
{
"from": {
"path": "LEGAL_ENTITY/LEGAL_ENTITY_DETAIL/FullName"
},
"to": {
"path": "has_organization_name/has_value"
}
}
]
}
}
]
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Forbidden
```
{
"message": "Invalid Api Key"
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `id` required | `string` path | `01H1Y44CSD0CQ7Z26S7QTJ2EF5` | Job id |
##### Response `200``application/json`
7 fields
Rules Generation Status
| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | Generation id |
| `status`required | `string` | Generation status`completed``failed``running` |
| `lang_from`required | `string` | Language to generate rules from |
| `lang_to`required | `string` | Language to generate rules to |
| `rules`required | `object[]` | Array of generated rules |
| `definition`required | `string` | Rule definition |
| `errors`required | `string[]` | Array of errors that occurred during generation. |
| `statistics` | `object` | Statistics of the generated mappings. |
| `mapped_properties_count`required | `integer` | The number of properties that were mapped. |
| `unmapped_properties_count`required | `integer` | The number of properties that were not mapped. |
| `coverage_ratio`required | `number (float)` | The percentage of properties that were mapped. |
| `unmapped_properties`required | `string[]` | The array of unmapped properties. |
| `mapped_properties`required | `object[]` | The array of mapped properties. |
| `foreign_path`required | `string` | The path to the property in the foreign language. |
| `staircase_path`required | `string` | The path to the property in the staircase language. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `403``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
### Monitoring Testing
`GET` `/testing/configurations`
#### Get Testing Configurations
`getTestingConfigurations`
**Retrieve registered testing configurations.
##### Response
400403404
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Response `200``application/json`
3 fields
Configurations retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `health_key` | `string` | Environment health key. |
| `host_environment` | `string` | Environment domain name. |
| `config_type` | `string` | Testing configuration type. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/testing/runs`
#### List Testing Runs
`listTestingRuns`
**Retrieve testing runs.
##### Response
400403404
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `testing_environment` | `string` query | `test.staircaseapi.com` | Testing Environment |
| `test_run_invocation_type` | `string` query | `http` | Testing run invocation type |
##### Response `200``application/json`
7 fields
Testing run retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | Unique test run id. |
| `test_run_status` | `string` | Test run status |
| `test_run_invocation_type` | `string` | Test run invocation type. |
| `test_run_result` | `object[]` | Test run result details. |
| `test_worker_id` | `string` | Test run worker id. |
| `expire_at` | `string` | Test run result expiration time. |
| `created_at` | `string` | Test run creation time. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`PUT` `/testing/configurations`
#### Create Testing Configuration
`createTestingConfiguration`
The primary function of this service is to enable the creation of testing configurations. The testing service, which is responsible for testing the language product against test cases generated from historical invocations, conducts multiple tests throughout the day. It should be noted that the test cases themselves are generated daily and have an expiration period of one month
##### Request
application/json Copy
```
{
"health_key": "health-key",
"host_environment": "lang.staircaseapi.com"
}
```
##### Response
200400403404422
application/json Copy Configuration response
```
{
"message": "Configuration created."
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
```
{
"message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `host_environment`required | `string` | Environment domain name. |
| `health_key`required | `string` | Health key. |
##### Response `200``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `422``application/json`
1 fields
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
`DELETE` `/testing/configurations/{host_environment}`
#### Delete Testing Configuration
`deleteTestingConfiguration`
This service removes configuration.
##### Response
200403404
application/json Copy Configuration response
```
{
"message": "Configuration deleted."
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `host_environment` required | `string` path | `lang.staircaseapi.com` | Environment domain name |
##### Response `200``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/testing/runs`
#### Start Testing Run
`startTestingRun`
The purpose of this service is to execute test cases in a specified environment. Upon invocation, the collected test cases will be run against the installed version of the Language product. Each individual run will be identified with a unique identifier, which will enable interested parties to query the corresponding result. It should be noted that the information pertaining to test run results will be valid for a period of two months before expiration
##### Request
application/json Copy
```
{
"api_key": "api-key",
"testing_environment": "lang.staircaseapi.com"
}
```
##### Response
200400403404
application/json Copy Test run response
```
{
"test_run_id": "01GSWG340T18R53MK6YYS64DD7"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `testing_environment`required | `string` | Environment domain name. |
| `api_key`required | `string` | API key. |
##### Response `200``application/json`
1 fields
Test run response
| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | Test run identifier. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/testing/runs/{test_run_id}`
#### Get Testing Run
`getTestingRun`
**Retrieve testing run.
##### Response
200400403404
application/json Copy Testing run retrieved successfully
```
{
"expire_at": "1683887213",
"test_run_status": "success",
"created_at": "2023-03-13T10:26:53.444553+00:00",
"test_run_id": "01GVD84EP2YPDWG6EMFH6K0NJZ",
"finished_at": "2023-03-13T10:30:58.736202+00:00",
"test_run_invocation_type": "http",
"test_run_result": [
{
"summary": {
"collected": "38",
"passed": "38",
"failed": "0",
"error": "0",
"xfailed": "0",
"skipped": "0"
},
"local_path": "/tmp/tmpw52i9gi5/01GVD84EP2YPDWG6EMFH6K0NJZ/2023-02-19",
"total_duration": "142.44527006149292",
"failed_test_cases": [],
"status": "OK"
}
],
"testing_environment": "test.staircaseapi.com",
"test_worker_id": "language-testing-runner-worker:859b57c4-82d3-482e-8b30-afb3f66871d7",
"logs": [
"[Container] 2023/03/13 10:28:27 Entering phase BUILD\n",
"[Container] 2023/03/13 10:28:27 Running command python3.9 testing_test_runner_codebuild_worker.py\n",
"{\"level\":\"INFO\",\"location\":\":270\",\"message\":\"Test Runner Worker started for test run: 01GVD84EP2YPDWG6EMFH6K0NJZ...\",\"timestamp\":\"2023-03-13 10:28:28,685+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:168\",\"message\":\"Preparing tests for date:2023-02-19\",\"timestamp\":\"2023-03-13 10:28:31,853+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:170\",\"message\":\"Preparing tests for env:-ce86d6bcfe.staircaseapi.com\",\"timestamp\":\"2023-03-13 10:28:31,853+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:195\",\"message\":\"Preparing test files finished /tmp/tmpw52i9gi5: 01GVD84EP2YPDWG6EMFH6K0NJZ\",\"timestamp\":\"2023-03-13 10:28:36,103+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"{\"level\":\"INFO\",\"location\":\"run_defined_tests:108\",\"message\":\"Running tests under /tmp/tmpw52i9gi5/01GVD84EP2YPDWG6EMFH6K0NJZ/2023-02-19\",\"timestamp\":\"2023-03-13 10:28:36,107+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"============================= test session starts ==============================\n",
"platform linux -- Python 3.9.16, pytest-7.2.0, pluggy-1.0.0\n",
"rootdir: /codebuild/output/src052753333/src\n",
"plugins: xdist-3.2.1, mock-3.10.0\n",
"gw0 I / gw1 I / gw2 I / gw3 I / gw4 I / gw5 I / gw6 I / gw7 I / gw8 I / gw9 I / gw10 I / gw11 I / gw12 I / gw13 I / gw14 I / gw15 I / gw16 I / gw17 I / gw18 I / gw19 I / gw20 I / gw21 I / gw22 I / gw23 I / gw24 I / gw25 I / gw26 I / gw27 I / gw28 I / gw29 I / gw30 I / gw31 I / gw32 I / gw33 I / gw34 I / gw35 I / gw36 I / gw37 I\n",
"gw0 [38] / gw1 [38] / gw2 [38] / gw3 [38] / gw4 [38] / gw5 [38] / gw6 [38] / gw7 [38] / gw8 [38] / gw9 [38] / gw10 [38] / gw11 [38] / gw12 [38] / gw13 [38] / gw14 [38] / gw15 [38] / gw16 [38] / gw17 [38] / gw18 [38] / gw19 [38] / gw20 [38] / gw21 [38] / gw22 [38] / gw23 [38] / gw24 [38] / gw25 [38] / gw26 [38] / gw27 [38] / gw28 [38] / gw29 [38] / gw30 [38] / gw31 [38] / gw32 [38] / gw33 [38] / gw34 [38] / gw35 [38] / gw36 [38] / gw37 [38]\n",
"\n",
"...................................... [100%]{\"level\":\"INFO\",\"location\":\"run_defined_tests:133\",\"message\":\"Test result: 0\",\"timestamp\":\"2023-03-13 10:30:58,733+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"{\"level\":\"INFO\",\"location\":\":276\",\"message\":\"Test Runner Finished in 150.050298212\",\"timestamp\":\"2023-03-13 10:30:58,736+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
"\n",
"======================== 38 passed in 142.45s (0:02:22) ========================\n",
"\n",
"[Container] 2023/03/13 10:30:58 Phase complete: BUILD State: SUCCEEDED\n",
"[Container] 2023/03/13 10:30:58 Phase context status code: Message: \n",
"[Container] 2023/03/13 10:30:58 Entering phase POST_BUILD\n",
"[Container] 2023/03/13 10:30:58 Phase complete: POST_BUILD State: SUCCEEDED\n",
"[Container] 2023/03/13 10:30:58 Phase context status code: Message: \n"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `test_run_id` required | `string` path | `01GST3JQ3DZT2GJ8DBBATN9VQ4` | Test run identifier |
##### Response `200``application/json`
9 fields
Testing run retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | Unique test run id. |
| `test_run_status` | `string` | Test run status |
| `test_run_invocation_type` | `string` | Test run invocation type. |
| `test_worker_id` | `string` | Test run worker id. |
| `expire_at` | `string` | Test run result expiration time. |
| `created_at` | `string` | Test run creation time. |
| `finished_at` | `string` | Test run result finish time. |
| `test_run_result` | `object[]` | Test run result details. |
| `logs` | `string[]` | Test run logs |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`PUT` `/monitoring/testing/data`
#### Create Update Testing Data
`createUpdateTestingData`
This endpoint enables users to create or update testing data in JSON format. The testing data can be either a translation file or a language file.
##### Request
TestTranslationDataExampleTestLanguageDataExample
application/json Copy
```
{
"file_path": "2023-03-12/test.staircaseapi.com/translations/staircase-graph_to_credit-input/111116VY6GRVSJVZV2CPCJYRYY_staircase-graph_to_credit-input.json",
"payload": {
"test": "data"
}
}
```
application/json Copy
```
{
"file_path": "2023-03-12/test.staircaseapi.com/languages/credit-input.json",
"payload": {
"test": "data"
}
}
```
##### Response
200400403404422
application/json Copy Configuration response
```
{
"message": "Test data created/updated."
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
```
{
"message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `file_path`required | `string` | Test data path. |
| `payload`required | `string` | Test data payload. |
##### Response `200``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `422``application/json`
1 fields
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
`GET` `/monitoring/testing/data/{file_path}`
#### Get Testing Data
`getTestingData`
This endpoint allows users to retrieve testing data in JSON format. The path to the testing data should be provided in the correct format, and it should be URL encoded.
##### Response
200400403404
application/json Copy Configurations retrieved successfully
```
{
"test": "data"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `file_path` required | `string` path | `2023-03-10%test.staircaseapi.com%2Ftranslations%2Fcredit-mismo34_to_staircase-graph%2F01GV60FP5813DD0EXJ2PK7K422_credit-mismo34_to_staircase-graph.json` | Testing data path |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`200`
`DELETE` `/monitoring/testing/data/{file_path}`
#### Delete Testing Data
`deleteTestingData`
This endpoint allows users to delete testing data with the provided path. Path should be URL encoded.
##### Response
200403404
application/json Copy Configuration response
```
{
"message": "Testing data deleted."
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `file_path` required | `string` path | `2023-03-10%test.staircaseapi.com%2Ftranslations%2Fcredit-mismo34_to_staircase-graph%2F01GV60FP5813DD0EXJ2PK7K422_credit-mismo34_to_staircase-graph.json` | Testing data path |
##### Response `200``application/json`
1 fields
Configuration response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Endpoint result message. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/testing/encryption/key`
#### Register Testing Data Private Key
`RegisterTestingDataPrivateKey`
Start Testing Run
This endpoint enables users to register their private key for RSA encryption and decryption. The private key should be provided in the PEM format. Once the private key is registered, it can be used to decrypt the symmetric key that is used for decrypting the testing data.
##### Request
application/json Copy
```
{
"key": ""
}
```
##### Response
200400403404
application/json Copy Key response
```
{
"message": "Key registered"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "API key is not valid."
}
```
application/json Copy Requested resource not found
```
{
"message": "Object not found"
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `key`required | `string` | Private key. |
##### Response `200``application/json`
1 fields
Key response
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Key registered. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Translate
`GET` `/translate/{translation_id}`
#### Retrieve Translation Status
`retrieveTranslatedPayload`
Retrieve Translation Status retrieves a translation status and the result, if available. The response will contain a signed URL for the file containing the result. This file will contain both the returned data and any warnings or errors detected during translation.
##### Response
200400403404
application/json Copy Translation status
```
{
"status": "SUCCEEDED",
"translation_id": "8519db-f03b-4a13-885b-5d67d338ea0",
"started_at": "2021-11-04 12:18:08.903000+00:00",
"translation": {
"output_url": "https://example_file.json?Expires=1627597250",
"mimetype": "application/json"
}
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `translation_id` required | `string` path | `f618ce80-dg5b-4ce2-9996-9d1d3240864d` | Translation ID |
##### Response `200``application/json`
4 fields
Translation status
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | Status description |
| `translation_id` | `string` | Translation ID |
| `started_at` | `string` | Time when translation started in DateTime format |
| `translation` | `object` | Signed URL for the document containing the output and media type of the translation |
| `output_url` | `string` | Signed URL for the document containing the output |
| `mimetype` | `string` | Media type of the translation`application/json``application/xml` |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
`POST` `/translate`
#### Translate Received Payload
`translateReceivedPayload`
Translating a received payload
Translate Received Payload translates any valid object in the Staircase data model from one language to another. Languages are identified by language_name.
In the request body, provide the language to translate from (lang_from), the language to translate to (lang_to). Call Retrieve Languages to retrieve language_name(s) for languages that exist in your environment.
Also, in the request body, provide both a valid Staircase data model object or snippet to be translated (data), and the version of Staircase language that the data model object/snippet belongs to. Call Retrieve Data Model Schema to retrieve a complete Staircase data model schema and all objects contained within.
Can also be used to translate between different staircase language/lexicon versions. Set 'lang_from' and 'lang_to' to 'staircase', and use sc_version_from, sc_version_to query parameters. See /lexicon for more info.
##### Request
application/json Copy
```
{ 'data': 'object data in customer_lang format', 'lang_from':'customer_lang', 'lang_to':'staircase' }
```
##### Response
200202400403404
application/json Copy 200 response
```
{
"type": "employment",
"permissible_purpose": "risk-assessment",
"target": {
"first_name": "First",
"last_name": "Last",
"social_security_number": "***-**-9999",
"contact_email": "joesmith@example.org",
"company": {
"name": "Truework Inc"
}
}
}
```
application/json Copy Async translation accepted
```
{
"translation_id": "8519db-f03b-4a13-885b-5d67d338ea0",
"started_at": "2021-11-04 12:18:08.903000+00:00",
"callback_url": "https://webhook.site/6788842-f03b-4a13-885b-5d67d338ea09"
}
```
application/json Copy Request data failed validation
```
{
"MissingData": {
"message": "{'data': ['Missing data for required field.']}"
},
"ValidationFailed": {
"message": "Invalid v0 paths detected",
"invalid_paths": [
{
"path": "$.deal_set.pawrty[0].individual.name.first",
"message": "Could not find the given path"
},
{
"path": "deal_set.partie[0].individual.name.last",
"message": "All valid paths are expected to start with $."
}
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Language not found"
}
```
##### Request body`application/json`
11 fields
| Field | Type | Description |
| --- | --- | --- |
| `lang_from`required | `string` | Language of the payload |
| `lang_to`required | `string` | Language of the desired translation |
| `include_missing` | `boolean` | Include mapped fields in output even if originals don't exist in input |
| `apply_lexicon_types` | `boolean` | Validates and converts output values according to their types specified in lexicon. Works only for translation to staircase v0 language. |
| `data`required | `object` | Any object in a valid Staircase model |
| `version` | `integer` | Version of staircase language`0``1` |
| `metadata` | `object` | Any metadata about this translation |
| `transaction_id` | `string` | Transaction ID associated with this translation. This value will be used in reporting to Health. |
| `collection_id` | `string` | Collection ID associated with this translation. This value will be used in reporting to Health. |
| `sc_version_from` | `integer` | For staircase to staircase translations - when lang_from and lang_to are staircase |
| `sc_version_to` | `integer` | For staircase to staircase translations = when lang_from and lang_to are staircase |
| `async` | `boolean` | When false, translation will be returned in a synchronous manner. If async is turned on, translation and translation status will need to be retrieved via Retrieve Translation. |
| `callback_url` | `string` | Webhook URL to receive translation result |
##### Response `202``application/json`
3 fields
Async translation accepted
| Field | Type | Description |
| --- | --- | --- |
| `translation_id` | `string` | Translation ID |
| `started_at` | `string` | Time when translation started in DateTime format |
| `callback_url` | `string` | Webhook URL to receive translation result |
##### Response `400``application/json`
2 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Error message |
| `invalid_paths` | `object[]` | Details about the request and invalidity |
| `path` | `string` | Path from the request |
| `message` | `string` | Details about invalidity |
##### Response `403``application/json`
2 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `url` | `string` | API URL |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Other responses
`200``422`
### Language Operations
`POST` `/product/products/language/invocations`
#### Extended Translate
`extendedTranslate`
Current Endpoint performs extended translation service, which includes invocation extension and entity translation along with regular translation.
In order to execute extended translation workflow provide `from_language`, `to_language` and `data` fields in the `request_data` object. Operation is async, in order to check status input "language" as `product_name` and returned `invocation_id` to retrieve status endpoint.
##### Request
application/json Copy
```
{
"request_data": {
"from_language": "staircase-graph",
"to_language": "test_language_1",
"data": {
"invocations": [
{
"has_invocation_code_type": {
"has_value": "40004"
}
}
],
"graph_entities": [
{
"has_data_path": {
"has_value": "person/has_first_name"
}
}
]
}
}
}
```
##### Response
202400404
application/json Copy Generated rules
```
{
"product_flow_name": "language-translation-workflow",
"metadata": {},
"response_collection_id": "01H7SQAMJ98YT3D0KJ9W99D647",
"invocation_mode": "single_flow",
"widget_url": "",
"invocation_id": "01H7SQAMJ98YT3D0KJ9W99D647",
"invocation_status": "STARTED",
"transaction_id": "01H7SQAK56R1DB10255J2M780K",
"request_collection_id": "01H7SQAMTH9A84SEBDMSCNCET5",
"request_data": {
"from_language": "staircase-graph",
"to_language": "test_language_1",
"data": {
"invocations": [
{
"has_invocation_code_type": {
"has_value": "40004"
}
}
],
"graph_entities": [
{
"has_data_path": {
"has_value": "person/has_first_name"
}
}
]
}
},
"api_id": null,
"_links": {
"health_metrics": "https://bushnell.staircaseapi.com/code-health-checker/metric/01H7SQAK56R1DB10255J2M780K?product_name=language"
}
}
```
application/json Copy Request data invalid
```
{
"message": "Request body is invalid."
}
```
application/json Copy Resource is not found
```
{
"message": "Job not found."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `request_data` | `object` | Request data. |
| `from_language` | `string` | Language name to translate from. |
| `to_language` | `string` | Language name to translate to. |
| `data` | `object` | Content to translate. |
##### Response `202``application/json`
9 fields
Generated rules
| Field | Type | Description |
| --- | --- | --- |
| `product_flow_name` | `string` | Name of the executed product flow. |
| `invocation_id` | `string` | Invocation ID. |
| `invocation_status` | `string` | Invocation Status.`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` |
| `transaction_id` | `string` | Transaction ID used for invocation. |
| `request_collection_id` | `string` | Request Collection ID. |
| `request_data` | `object` | Input data. |
| `response_collection_id` | `string` | Response Collection ID. |
| `widget_url` | `string (uri)` | URL of the widget. |
| `metadata` | `object` | Response collection metadata. |
##### Response `400``application/json`
1 fields
Request data invalid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
##### Response `404``application/json`
1 fields
Resource is not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
### Operations
`POST` `/hello-world`
#### Hello World
Dummy hello world endpoint
##### Other responses
`200`
`GET` `/info`
#### Info endpoint
Placeholder endpoint. As this is a language repo, it must be used in conjunction with the Translator Service.
##### Other responses
`200`
`POST` `/languages`
#### Export language
`export_language`
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | API key |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `langugage_description_url` | `string` | — |
##### Response `201``application/json`
1 fields
201 response
| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | — |
##### Response `400``application/json`
1 fields
No language by specified url
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
## Errors
`400``403``404``422``500`
## More in Data
- Previous product: Content
- Next product: ML
---
# ML
# ML
Document and image models: signature detection, hosted document extraction, and the training-data pipelines behind them.
Two model families. Signature detection answers whether a page carries a signature and where, which is what makes an executed-document check automatic. Document extraction reads fields from a page image.
Training data comes from a labelling pipeline that annotates real mortgage documents rather than generated ones, and accuracy per vendor and per document type is reported by Document.
## How it works
Hosting a vendor's extraction engine rather than calling its API was a deliberate option, and the deployment path for it is Host. The choice turns on where the document is allowed to be, not on which is easier to integrate.
## Operations
### AWSDocumentAI
`POST` `/document`
#### OCR process document
`document`
Long-running operation endpoint to process document by AWS Textract OCR.
##### Request
application/json Copy An example of a batch request. Presigned URLs shown here are just examples, you need to provide valid and active Presigned URLs when making the request.
```
{
"urls": [
"https://somebucketname.s3.us-east-1.amazonaws.com/test.pdf?X-Amz-Algorithm=&X-Amz-Credential=%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=&X-Amz-Expires=1800&X-Amz-Signature=&X-Amz-SignedHeaders=host",
"https://somebucketname.s3.us-east-1.amazonaws.com/MultiDocs_10_pages.pdf?X-Amz-Algorithm=&X-Amz-Credential=%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=&X-Amz-Expires=1800&X-Amz-Signature=&X-Amz-SignedHeaders=host",
"https://somebucketname.s3.us-east-1.amazonaws.com/Form1040_Leo.pdf?X-Amz-Algorithm=&X-Amz-Credential=%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=&X-Amz-Expires=1800&X-Amz-Signature=&X-Amz-SignedHeaders=host"
]
}
```
##### Response
200400 application/json400 text/html401403
application/json Copy Ok.
```
{
"documents_info": [
{
"uuid": "2db2abe018862e9c4e4cf340696da14ecf3ff37ba153d68ab6796433468e5e48",
"url": "https://files.consumerfinance.gov/f/201311_cfpb_kbyo_closing-disclosure.pdf"
}
]
}
```
application/json Copy Bad Request.
```
{
"code": "Bad Request",
"message": "Bad request syntax or unsupported method"
}
```
text/html Copy Bad Request.
```
Bad request syntax or unsupported method
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `urls`required | `string[]` | One or more Presigned URLs of PDFs to extract data from. |
| `processor` | `string` | Name of AWS DocumentAI processor to be used for data extractionExample `irs_w2` |
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `documents_info` | `object[]` | Array of IDs for query results of OCR. |
| `uuids` | `object` | UUIDs associated with the documents being processed as part of the batch. |
##### Response `400``application/json`
1 fields
Bad Request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad Request error. |
| `code`required | `one of` | Bad Request |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`GET` `/test-model/{job_id}`
#### Retrieve Extracted Data
`test-model-status`
Get test train document status
This service allows getting result of test model.
##### Response
200401403404
application/json Copy Ok.
```
{
"code": 200,
"pages": [
{
"num": 1,
"width": 612,
"height": 792,
"id": "01FQ1V5WYZCKMAZ0DQQNTVPC3C"
}
],
"annotations": [
{
"annotation_spec_id": 5708576960238584000,
"display_name": "has_social_security_number",
"text_extraction": {
"score": 0.9998301267623901,
"text_segment": {
"start_offset": 86,
"end_offset": 96,
"content": "123-45-678"
}
},
"page": "01FQ1V5WYZCKMAZ0DQQNTVPC3C",
"bounding_box": {
"top_ratio": 0.7323232293128967,
"left_ratio": 0.4901960790157318,
"height_ratio": 0.012626290321350098,
"width_ratio": 0.09477123618125916
}
}
],
"document_text": "For Official Use Only\nOMB No. XXXXXXX\n22222\na Employee's social security number\nVoid\n123-45-678",
"transaction_id": "df5039ba-c650-4e73-8b0a-af6e0b031c15",
"train_product_id": "01FQBA6JJNHHN57RBKP0VZPYV4",
"processed_pages_count": 8,
"units": 33
}
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy File not found
```
{
"code": "Not Found",
"message": "Nothing matches the given URI"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string` path | `d8b01c18-10f7-4a71-962-43eeaed5ae6b` | Job ID of the test document operation. |
##### Response `200``application/json`
8 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `number` | Test model status code.Example `200` |
| `pages` | `object[]` | List of pages. |
| `id` | `string` | Unique page identifier.Example `01FQ1V5WYZMGW5SQTKQH1DSMTX` |
| `num` | `number` | Page number.Example `1` |
| `width` | `number` | Page width in points.Example `612` |
| `height` | `number` | Page height in points.Example `792` |
| `annotations` | `object[]` | Annotations elements |
| `annotation_spec_id` | `integer` | Annotation identification. |
| `display_name` | `string` | Annotation name. |
| `text_extraction` | `object` | Extraction object. |
| `score` | `number` | Annotation score. |
| `text_segment` | `object` | Text Segment object. |
| `start_offset` | `integer` | Character offsets rather than byte offsets. |
| `end_offset` | `integer` | Character offsets rather than byte offsets. |
| `content` | `string` | Annotation content. |
| `page` | `string` | Page identifier.Example `01FQ1V5WYZMGW5SQTKQH1DSMTX` |
| `bounding_box` | `object` | Bounding boxes of extracted text. |
| `top_ratio` | `number` | Top ratio of bounding boxExample `0.7462121248245239` |
| `left_ratio` | `number` | Left ratio of bounding boxExample `0.779411792755127` |
| `height_ratio` | `number` | Height ratio of bounding boxExample `0.010101020336151123` |
| `width_ratio` | `number` | Width ratio of bounding boxExample `0.026143789291381836` |
| `train_product_id` | `string` | Unique train product execution ID.Example `01FQBA6JJNHHN57RBKP0VZPYV4` |
| `transaction_id` | `string` | Transaction ID for the generated health metrics.Example `df5039ba-c650-4e73-8b0a-af6e0b031c15` |
| `document_text` | `string` | Content of extract file.Example `For Official Use Only OMB No. XXXXXXX 22222 a Employee's social security number Void 123-45-678` |
| `processed_pages_count` | `number` | Count of processed pages. It can be the same or less than in the original document.Example `8` |
| `units` | `number` | Count of comprehend units used for extraction.Example `33` |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
File not found
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | File not found error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Reason why document was not extracted.Example `Test model result contains overlapped annotations` |
`POST` `/generate-gs`
#### Convert GTL and OCR to annotations
`generate-gs`
Convert GTL and OCR input to annotations. Annotations will be used for training models for AWS Comprehend.
##### Request
application/json Copy
```
{
"gtl": {
"documents": [
{
"@type": "closing_disclosure"
}
]
},
"gc_presigned_download_urls": [
"https://dev-data-manager-blobs-bucket-us-east-1-1111111.s3.amazonaws.com/foo.json?"
]
}
```
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `gtl`required | `object` | Input from GTL |
| `documents` | `object[]` | Array of documents from GTL |
| `@type`required | `string` | Document typeExample `closing_disclosure` |
| `gc_presigned_download_urls`required | `string[]` | Presigned URL for document |
##### Response `200``application/json`
2 fields
Successful response.
| Field | Type | Description |
| --- | --- | --- |
| `annotations` | `object[]` | Array of labels, contains label name, value, GTL value and text segment info. |
| `displayName` | `string` | Data point (label) name |
| `value` | `string` | Value for this data point |
| `gtlValue` | `string` | GTL value for this data point, usually V2 output |
| `textExtraction` | `object` | Data about where this data point is located in document |
| `page` | `number` | Page numberExample `1` |
| `textSegment` | `object` | Where data point text starts and ends. |
| `startOffset` | `number` | Index of text start |
| `endOffset` | `number` | Index of text end |
| `document` | `object` | Data about text for each page in document |
| `documentText` | `object` | Object with data for text extracted |
##### Response `400``application/json`
1 fields
Incorrect payload
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Reason why request was not processed.Example `Error on getting data from presigned URL` |
`GET` `/models`
#### Retrieve Trained Models
`get-models`
Get trained models
This service allows getting a list of trained Comprehend models.
##### Response
200401
application/json Copy Ok.
```
{
"count": 2,
"models": [
{
"name": "mortgage-insurance-certificate",
"versions": [
{
"name": "2022-05-12-10-25-09",
"precision": 62.68656716417911,
"annotations": [
"has_organization_name",
"has_insurance_policy_identifier",
"has_insurance_policy_effective_date",
"has_mortgage_insurance_premium_rate_percent",
"has_mortgage_insurance_duration_type",
"has_mortgage_insurance_premium_paid_by_type",
"has_mortgage_insurance_coverage_percent",
"has_mortgage_insurance_premium_refundable_type",
"has_mortgage_insurance_premium_calculation_type",
"has_mortgage_insurance_third_premium_rate_percent",
"has_mortgage_insurance_subsequent_premium_rate_percent"
]
}
]
},
{
"name": "closing-disclosure",
"versions": [
{
"name": "2022-05-12-13-49-36",
"precision": 72.83441367118444,
"annotations": [
"applicant_document_date",
"product",
"loan_type",
"sale_price",
"interest_rate",
"monthly_principal_interest",
"mortgage_insurance_required",
"property_taxes_in_escrow",
"homeowners_insurance_in_escrow",
"prepaid_property_taxes_months",
"prepaid_property_taxes_amount",
"loan_disclosures_assumption",
"loan_disclosures_late_payment",
"applicant_document_signature"
]
},
{
"name": "2022-03-31-20-54-33",
"precision": 58.03921568627452,
"annotations": [
"has_prepaid_taxes_months_count",
"has_prepaid_taxes_amount",
"has_assumability_indicator",
"has_late_charge_type",
"has_document_date",
"has_loan_amortization_type",
"has_mortgage_insurance_required_indicator",
"has_tax_escrow_required_indicator",
"has_hazard_insurance_escrow_required_indicator"
]
}
]
}
]
}
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `count` | `number` | Count of trained modelsExample `11` |
| `models` | `object[]` | List of models. |
| `name` | `string` | Model name.Example `closing-disclosure` |
| `versions` | `object[]` | List of versions. |
| `name` | `string` | Version name.Example `2022-05-12-10-25-09` |
| `precision` | `number` | Version precision.Example `70.35830618892508` |
| `annotations` | `string[]` | List of trained annotations. |
| `status` | `string` | Status of the version. Only trained or imported models are used for extraction.Example `TRAINED` |
| `message` | `string` | Message about model version status.Example `TRAINED` |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`POST` `/setting`
#### Settings
`settings`
AWS Comprehend settings. Can be used for update inference units count to increase throughput. 1 inference unit corresponds to throughput in 100 characters per second.
##### Request
application/json Copy
```
{
"inference_units_count": 3
}
```
##### Response
202400 application/json400 text/html403
application/json Copy Request accepted.
```
{
"message": "Settings have been successfully updated"
}
```
application/json Copy Bad Request.
```
{
"code": "Bad Request",
"message": "Bad request syntax or unsupported method"
}
```
text/html Copy Bad Request.
```
Bad request syntax or unsupported method
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `inference_units_count`required | `integer` | Comprehend inference units count. |
##### Response `202``application/json`
1 fields
Request accepted.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Response message |
##### Response `400``application/json`
1 fields
Bad Request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad Request error. |
| `code`required | `one of` | Bad Request |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
### ML
`POST` `/extract`
#### Detect human signature
`detectSignature`
Check if PDF contains a human written signature
##### Response
200400 application/json400 text/html403
application/json Copy Ok.
```
{
"job_id": "WB6XV833KNWF0GZ7"
}
```
application/json Copy Bad Request.
```
{
"message": "Bad request syntax or unsupported method"
}
```
text/html Copy Bad Request.
```
Bad request syntax or unsupported method
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
##### Response `200``application/json`
1 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `job_id` | `string` | Extraction job ID |
##### Response `400``application/json`
1 fields
Bad Request.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
`POST` `/extract/{job_id}`
#### Detect human signature status
`detectSignatureStatus`
Check status of extraction job
##### Response
200400 application/json400 text/html403404
application/json Copy Ok.
```
{
"is_signed": true,
"page": 7
}
```
application/json Copy Bad Request.
```
{
"message": "Bad request syntax or unsupported method"
}
```
text/html Copy Bad Request.
```
Bad request syntax or unsupported method
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"message": "Extraction job not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string` path | `WB6XV833KNWF0GZ7` | Extraction Job ID. |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `is_signed` | `boolean` | Is document signed |
| `page` | `number` | Page with signature |
##### Response `400``application/json`
1 fields
Bad Request.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `404``application/json`
1 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
### Platform
`GET` `/products/train_data_extraction/response-schema`
#### Retrieve Response Schema
`retrieveResponseSchema`
Retrieve Schema retrieves a JSON schema for the response returned by the product. It can also return an example for the response output object through return_example attribute.
##### Response
200400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500
application/json Copy Successfully returned the list of elements of response of the product waterfall.
```
{
"addresses": [
{
"address_line_1_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "56319 Underwood Views",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MQEN90HSCMPQWCAD",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.13863636363636364,
"has_bounding_box_width_ratio": 0.23529411764705882,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"address_line_2_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Lake Debramouth NE 33667-9751",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ110EKH48ZQEK3YQFF",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.07352941176470588,
"has_bounding_box_top_ratio": 0.15636363636363637,
"has_bounding_box_width_ratio": 0.31411764705882356,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"documents": [
{
"@id": "01FBHN4YR48XC75HJF5Z9VRBTV",
"@type": "irs_w2",
"has_staircase_blob_identifier": {
"has_value": "01FBHN11S8SF835QXB8M1EBZGG"
},
"with_page_extraction_metadata": [
{
"@id": "01FBHPXCJ03V0AAHVGW6G1YE08",
"page_height": 2200,
"page_number": 1,
"page_width": 1700
}
]
}
],
"employment": [
{
"retirement_plan_participant_indicator": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "x",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1BN0A4XXXG5ZSD8K0",
"has_bounding_box_height_ratio": 0.013181818181818182,
"has_bounding_box_left_ratio": 0.6194117647058823,
"has_bounding_box_top_ratio": 0.26590909090909093,
"has_bounding_box_width_ratio": 0.02,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"income": [
{
"allocated_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1ZTCHXGVK108FHVHE",
"has_bounding_box_height_ratio": 0.016363636363636365,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.17227272727272727,
"has_bounding_box_width_ratio": 0.10058823529411764,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"dependent_care_benefits_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "219",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MM5FMP6HGKC606ZD",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8129411764705883,
"has_bounding_box_top_ratio": 0.2018181818181818,
"has_bounding_box_width_ratio": 0.04352941176470588,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_1_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "678-77-709",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1W0SMD3JVDE47N116",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.1288235294117647,
"has_bounding_box_top_ratio": 0.3663636363636364,
"has_bounding_box_width_ratio": 0.11411764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_2_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "940-46-434",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ12M1K4ASVZBF68XHJ",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.12823529411764706,
"has_bounding_box_top_ratio": 0.39181818181818184,
"has_bounding_box_width_ratio": 0.11588235294117646,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"federal_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "40043.57",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FE1EQ8X9Q3N12W4F",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.77,
"has_bounding_box_top_ratio": 0.09181818181818181,
"has_bounding_box_width_ratio": 0.09058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9966",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P0KJ87SMG4T98B75",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.23318181818181818,
"has_bounding_box_width_ratio": 0.05058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FF708969HFCH40NT",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7847058823529411,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.021176470588235293,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12b_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "284",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1VT54M1WB8JCK60N2",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.2636363636363636,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "307",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1122YD0V4AVKZENYF",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.295,
"has_bounding_box_width_ratio": 0.03705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ17CSM3TM4RXJ81SBQ",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.29545454545454547,
"has_bounding_box_width_ratio": 0.02823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "242",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ14CVKQT2JE5BGCGCG",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.3277272727272727,
"has_bounding_box_width_ratio": 0.03764705882352941,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "H",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ15PYMH0E9SDPSFAFS",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.3286363636363636,
"has_bounding_box_width_ratio": 0.02588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FRRA33BQ5Y1WPBZB",
"has_bounding_box_height_ratio": 0.015,
"has_bounding_box_left_ratio": 0.5735294117647058,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.09823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "4419.8",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ165FBQES8CNY03WXV",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.07176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"nonqualified_retirement_plan_distribution_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "233",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1SH6XFDXZEW448H6A",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MX04VCHK51H8RMF2",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.10705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9459.67",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1X5EE4TPRBM2CH0M3",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.768235294117647,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.07882352941176471,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P9044AEFH8EF6QT7",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.175,
"has_bounding_box_width_ratio": 0.10470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"wages_salaries_tips_and_other_compensation_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "126204.09",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1Y43WKTXBJJWHE106",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.08954545454545454,
"has_bounding_box_width_ratio": 0.10588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"mortgage_products": [
{
"@id": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"@type": "groundtruth_labeling",
"has_service_request_date": {
"has_value": "2021-07-26"
},
"has_service_response_date": {
"has_value": "2021-07-26"
},
"product_used_for": "01FBHN4YR48XC75HJF5Z9VRBTV"
}
],
"organizations": [
{
"organization_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "39-3114215",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0H5YE99DKRNXTVR5W",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.08058823529411764,
"has_bounding_box_top_ratio": 0.09136363636363637,
"has_bounding_box_width_ratio": 0.12,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"organization_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Carlson Group Group",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1NYMK9JRAAMF3GXRH",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.07470588235294118,
"has_bounding_box_top_ratio": 0.11954545454545455,
"has_bounding_box_width_ratio": 0.2211764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"people": [
{
"full_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Taylor Cox",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1011XSCSZ76ZE1CX0",
"has_bounding_box_height_ratio": 0.02181818181818182,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.2381818181818182,
"has_bounding_box_width_ratio": 0.13470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_number": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "999-00-0000",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0VCNHZCXPKJ3WY9C8",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.26588235294117646,
"has_bounding_box_top_ratio": 0.06363636363636363,
"has_bounding_box_width_ratio": 0.1288235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
]
}
```
application/json Copy Error
```
{
"message": "Please provide one of valid return examples values: true, false"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Resource not found
```
{
"description": "Error Message.",
"type": "string"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | The environment API key. |
| `return_examples` | `boolean` query | `false` | If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false` |
##### Response `200``application/json`
1 fields
Successfully returned the list of elements of response of the product waterfall.
| Field | Type | Description |
| --- | --- | --- |
| `schema` | `object` | Element key / value element |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message. |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`GET` `/transactions/{transaction_id}/collections`
#### Retrieve Transaction Collections
`RetrieveTransactionCollections`
Retrieve Transaction Collections returns the content of a given `collection_id` associated with a specific `transaction_id`.
##### Response
200400403404500
application/json Copy Transaction collection retrieved successfully
```
{
"data": {}
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Resource not found
```
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | The environment API key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
##### Response `200``application/json`
4 fields
Transaction collection retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `array` | The data |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema |
| `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`PUT` `/transactions/{transaction_id}/collections/{collection_id}`
#### Update Collection
`updateCollection`
Update Collection allows you to update the content of a given `collection_id` associated with a `transaction_id`.
##### Request
application/json Copy
```
{
"addresses": [
{
"address_line_1_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "56319 Underwood Views",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MQEN90HSCMPQWCAD",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.13863636363636364,
"has_bounding_box_width_ratio": 0.23529411764705882,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"address_line_2_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Lake Debramouth NE 33667-9751",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ110EKH48ZQEK3YQFF",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.07352941176470588,
"has_bounding_box_top_ratio": 0.15636363636363637,
"has_bounding_box_width_ratio": 0.31411764705882356,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"documents": [
{
"@id": "01FBHN4YR48XC75HJF5Z9VRBTV",
"@type": "irs_w2",
"has_staircase_blob_identifier": {
"has_value": "01FBHN11S8SF835QXB8M1EBZGG"
},
"with_page_extraction_metadata": [
{
"@id": "01FBHPXCJ03V0AAHVGW6G1YE08",
"page_height": 2200,
"page_number": 1,
"page_width": 1700
}
]
}
],
"employment": [
{
"retirement_plan_participant_indicator": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "x",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1BN0A4XXXG5ZSD8K0",
"has_bounding_box_height_ratio": 0.013181818181818182,
"has_bounding_box_left_ratio": 0.6194117647058823,
"has_bounding_box_top_ratio": 0.26590909090909093,
"has_bounding_box_width_ratio": 0.02,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"income": [
{
"allocated_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1ZTCHXGVK108FHVHE",
"has_bounding_box_height_ratio": 0.016363636363636365,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.17227272727272727,
"has_bounding_box_width_ratio": 0.10058823529411764,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"dependent_care_benefits_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "219",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MM5FMP6HGKC606ZD",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8129411764705883,
"has_bounding_box_top_ratio": 0.2018181818181818,
"has_bounding_box_width_ratio": 0.04352941176470588,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_1_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "678-77-709",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1W0SMD3JVDE47N116",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.1288235294117647,
"has_bounding_box_top_ratio": 0.3663636363636364,
"has_bounding_box_width_ratio": 0.11411764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_2_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "940-46-434",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ12M1K4ASVZBF68XHJ",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.12823529411764706,
"has_bounding_box_top_ratio": 0.39181818181818184,
"has_bounding_box_width_ratio": 0.11588235294117646,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"federal_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "40043.57",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FE1EQ8X9Q3N12W4F",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.77,
"has_bounding_box_top_ratio": 0.09181818181818181,
"has_bounding_box_width_ratio": 0.09058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9966",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P0KJ87SMG4T98B75",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.23318181818181818,
"has_bounding_box_width_ratio": 0.05058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FF708969HFCH40NT",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7847058823529411,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.021176470588235293,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12b_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "284",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1VT54M1WB8JCK60N2",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.2636363636363636,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "307",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1122YD0V4AVKZENYF",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.295,
"has_bounding_box_width_ratio": 0.03705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ17CSM3TM4RXJ81SBQ",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.29545454545454547,
"has_bounding_box_width_ratio": 0.02823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "242",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ14CVKQT2JE5BGCGCG",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.3277272727272727,
"has_bounding_box_width_ratio": 0.03764705882352941,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "H",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ15PYMH0E9SDPSFAFS",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.3286363636363636,
"has_bounding_box_width_ratio": 0.02588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FRRA33BQ5Y1WPBZB",
"has_bounding_box_height_ratio": 0.015,
"has_bounding_box_left_ratio": 0.5735294117647058,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.09823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "4419.8",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ165FBQES8CNY03WXV",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.07176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"nonqualified_retirement_plan_distribution_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "233",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1SH6XFDXZEW448H6A",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MX04VCHK51H8RMF2",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.10705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9459.67",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1X5EE4TPRBM2CH0M3",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.768235294117647,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.07882352941176471,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P9044AEFH8EF6QT7",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.175,
"has_bounding_box_width_ratio": 0.10470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"wages_salaries_tips_and_other_compensation_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "126204.09",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1Y43WKTXBJJWHE106",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.08954545454545454,
"has_bounding_box_width_ratio": 0.10588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"mortgage_products": [
{
"@id": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"@type": "groundtruth_labeling",
"has_service_request_date": {
"has_value": "2021-07-26"
},
"has_service_response_date": {
"has_value": "2021-07-26"
},
"product_used_for": "01FBHN4YR48XC75HJF5Z9VRBTV"
}
],
"organizations": [
{
"organization_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "39-3114215",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0H5YE99DKRNXTVR5W",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.08058823529411764,
"has_bounding_box_top_ratio": 0.09136363636363637,
"has_bounding_box_width_ratio": 0.12,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"organization_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Carlson Group Group",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1NYMK9JRAAMF3GXRH",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.07470588235294118,
"has_bounding_box_top_ratio": 0.11954545454545455,
"has_bounding_box_width_ratio": 0.2211764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"people": [
{
"full_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Taylor Cox",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1011XSCSZ76ZE1CX0",
"has_bounding_box_height_ratio": 0.02181818181818182,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.2381818181818182,
"has_bounding_box_width_ratio": 0.13470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_number": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "999-00-0000",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0VCNHZCXPKJ3WY9C8",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.26588235294117646,
"has_bounding_box_top_ratio": 0.06363636363636363,
"has_bounding_box_width_ratio": 0.1288235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
]
}
```
##### Response
200400 UpdateCollectionError400 text/html403404 UpdateCollectionError404 text/html500
application/json Copy Collection updated successfully
```
{
"addresses": [
{
"address_line_1_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "56319 Underwood Views",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MQEN90HSCMPQWCAD",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.13863636363636364,
"has_bounding_box_width_ratio": 0.23529411764705882,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"address_line_2_text": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Lake Debramouth NE 33667-9751",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ110EKH48ZQEK3YQFF",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.07352941176470588,
"has_bounding_box_top_ratio": 0.15636363636363637,
"has_bounding_box_width_ratio": 0.31411764705882356,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"documents": [
{
"@id": "01FBHN4YR48XC75HJF5Z9VRBTV",
"@type": "irs_w2",
"has_staircase_blob_identifier": {
"has_value": "01FBHN11S8SF835QXB8M1EBZGG"
},
"with_page_extraction_metadata": [
{
"@id": "01FBHPXCJ03V0AAHVGW6G1YE08",
"page_height": 2200,
"page_number": 1,
"page_width": 1700
}
]
}
],
"employment": [
{
"retirement_plan_participant_indicator": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "x",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1BN0A4XXXG5ZSD8K0",
"has_bounding_box_height_ratio": 0.013181818181818182,
"has_bounding_box_left_ratio": 0.6194117647058823,
"has_bounding_box_top_ratio": 0.26590909090909093,
"has_bounding_box_width_ratio": 0.02,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"income": [
{
"allocated_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1ZTCHXGVK108FHVHE",
"has_bounding_box_height_ratio": 0.016363636363636365,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.17227272727272727,
"has_bounding_box_width_ratio": 0.10058823529411764,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"dependent_care_benefits_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "219",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MM5FMP6HGKC606ZD",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8129411764705883,
"has_bounding_box_top_ratio": 0.2018181818181818,
"has_bounding_box_width_ratio": 0.04352941176470588,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_1_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "678-77-709",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1W0SMD3JVDE47N116",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.1288235294117647,
"has_bounding_box_top_ratio": 0.3663636363636364,
"has_bounding_box_width_ratio": 0.11411764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"employer_state_2_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "940-46-434",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ12M1K4ASVZBF68XHJ",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.12823529411764706,
"has_bounding_box_top_ratio": 0.39181818181818184,
"has_bounding_box_width_ratio": 0.11588235294117646,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"federal_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "40043.57",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FE1EQ8X9Q3N12W4F",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.77,
"has_bounding_box_top_ratio": 0.09181818181818181,
"has_bounding_box_width_ratio": 0.09058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9966",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P0KJ87SMG4T98B75",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8182352941176471,
"has_bounding_box_top_ratio": 0.23318181818181818,
"has_bounding_box_width_ratio": 0.05058823529411765,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12a_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FF708969HFCH40NT",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7847058823529411,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.021176470588235293,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12b_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "284",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1VT54M1WB8JCK60N2",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.2636363636363636,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "307",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1122YD0V4AVKZENYF",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.295,
"has_bounding_box_width_ratio": 0.03705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12c_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "P",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ17CSM3TM4RXJ81SBQ",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.29545454545454547,
"has_bounding_box_width_ratio": 0.02823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "242",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ14CVKQT2JE5BGCGCG",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.8188235294117647,
"has_bounding_box_top_ratio": 0.3277272727272727,
"has_bounding_box_width_ratio": 0.03764705882352941,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"irs_w2_box_12d_code": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "H",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ15PYMH0E9SDPSFAFS",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.7817647058823529,
"has_bounding_box_top_ratio": 0.3286363636363636,
"has_bounding_box_width_ratio": 0.02588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "152406.79",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1FRRA33BQ5Y1WPBZB",
"has_bounding_box_height_ratio": 0.015,
"has_bounding_box_left_ratio": 0.5735294117647058,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.09823529411764706,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"medicare_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "4419.8",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ165FBQES8CNY03WXV",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.8176470588235294,
"has_bounding_box_top_ratio": 0.14772727272727273,
"has_bounding_box_width_ratio": 0.07176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"nonqualified_retirement_plan_distribution_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "233",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1SH6XFDXZEW448H6A",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.23272727272727273,
"has_bounding_box_width_ratio": 0.04176470588235294,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_income_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1MX04VCHK51H8RMF2",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.10705882352941176,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tax_withheld_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "9459.67",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1X5EE4TPRBM2CH0M3",
"has_bounding_box_height_ratio": 0.017272727272727273,
"has_bounding_box_left_ratio": 0.768235294117647,
"has_bounding_box_top_ratio": 0.11818181818181818,
"has_bounding_box_width_ratio": 0.07882352941176471,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_tips_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "123655.86",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1P9044AEFH8EF6QT7",
"has_bounding_box_height_ratio": 0.014090909090909091,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.175,
"has_bounding_box_width_ratio": 0.10470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"wages_salaries_tips_and_other_compensation_amount": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "126204.09",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1Y43WKTXBJJWHE106",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.571764705882353,
"has_bounding_box_top_ratio": 0.08954545454545454,
"has_bounding_box_width_ratio": 0.10588235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"mortgage_products": [
{
"@id": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"@type": "groundtruth_labeling",
"has_service_request_date": {
"has_value": "2021-07-26"
},
"has_service_response_date": {
"has_value": "2021-07-26"
},
"product_used_for": "01FBHN4YR48XC75HJF5Z9VRBTV"
}
],
"organizations": [
{
"organization_identifier": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "39-3114215",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0H5YE99DKRNXTVR5W",
"has_bounding_box_height_ratio": 0.015454545454545455,
"has_bounding_box_left_ratio": 0.08058823529411764,
"has_bounding_box_top_ratio": 0.09136363636363637,
"has_bounding_box_width_ratio": 0.12,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"organization_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Carlson Group Group",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1NYMK9JRAAMF3GXRH",
"has_bounding_box_height_ratio": 0.01681818181818182,
"has_bounding_box_left_ratio": 0.07470588235294118,
"has_bounding_box_top_ratio": 0.11954545454545455,
"has_bounding_box_width_ratio": 0.2211764705882353,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
],
"people": [
{
"full_name": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "Taylor Cox",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ1011XSCSZ76ZE1CX0",
"has_bounding_box_height_ratio": 0.02181818181818182,
"has_bounding_box_left_ratio": 0.07588235294117647,
"has_bounding_box_top_ratio": 0.2381818181818182,
"has_bounding_box_width_ratio": 0.13470588235294118,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
},
"social_security_number": {
"data_sourced_from": "01FBHN4YR4H8E04K9RJZ3F8CRH",
"has_value": "999-00-0000",
"with_data_extraction_metadata": {
"@id": "01FBHPXCJ0VCNHZCXPKJ3WY9C8",
"has_bounding_box_height_ratio": 0.015909090909090907,
"has_bounding_box_left_ratio": 0.26588235294117646,
"has_bounding_box_top_ratio": 0.06363636363636363,
"has_bounding_box_width_ratio": 0.1288235294117647,
"with_page_extraction_metadata": "01FBHPXCJ03V0AAHVGW6G1YE08"
}
}
}
]
}
```
application/json Copy Error
```
{
"description": "Error details.",
"message": "Unable to update collection. Please check the collection data"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Resource not found
```
{
"message": "Unable to update collection. Please check the given ids"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | The environment API key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
| `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Staircase collection_id |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `data` | `object` | The data object |
##### Response `200``application/json`
1 fields
Collection updated successfully
| Field | Type | Description |
| --- | --- | --- |
| `data` | `object` | The data object |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
### DocumentAI
`POST` `/setup-credentials`
#### Set Up Google Cloud Account Credentials
`setup-credentials`
Setup Google Cloud service account credentials
Setup Google Cloud credentials in the form of a service account key in order to authenticate an application as a service account.
##### Request
application/json Copy An example of a Google Cloud service account key. The key shown is just an example, you need to provide a valid key in order to use the service.
```
{
"type": "service_account",
"project_id": "my-great-project-1234560",
"private_key_id": "aeb28addda999e5dde66de00041a1fd99ed7e4a32",
"private_key": "",
"client_email": "name-of-the-service-account@my-great-project-1234560.iam.gserviceaccount.com",
"client_id": "378463746364563353673",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/name-of-the-service-account%40my-great-project-1234560.iam.gserviceaccount.com"
}
```
##### Response
200400 application/json400 text/html401403408409500501502503
application/json Copy Ok.
```
{
"code": "200",
"message": "The credentials have been saved."
}
```
application/json Copy Bad Request.
```
{
"code": "Bad Request",
"message": "Bad request syntax or unsupported method"
}
```
text/html Copy Bad Request.
```
Bad request syntax or unsupported method
```
application/json Copy Unauthorized.
```
{
"code": "401",
"message": "This token is not valid for this service."
}
```
application/json Copy Forbidden
```
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
```
application/json Copy Request Timeout.
```
{
"code": "408",
"message": "SoftworksAI partner is not available."
}
```
application/json Copy Conflict
```
{
"code": "409",
"message": "Batch already exists"
}
```
application/json Copy Internal Server Error
```
{
"code": "500",
"message": "Internal Server Error"
}
```
application/json Copy Not Implemented
```
{
"code": "501",
"message": "Error"
}
```
application/json Copy Bad Gateway
```
{
"code": "502",
"message": "Error"
}
```
application/json Copy Service Unavailable
```
{
"code": "503",
"message": "Error"
}
```
##### Request body`application/json`
10 fields
| Field | Type | Description |
| --- | --- | --- |
| `type`required | `string` | The type of member this key is for.Example `service_account` |
| `project_id`required | `string` | The project identifier.Example `my-great-project-1234560` |
| `private_key_id`required | `string` | The project key identifier.Example `aeb28addda999e5dde66de00041a1fd99ed7e4a32` |
| `private_key`required | `string` | The private key contents.Example `` |
| `client_email`required | `string` | The client emails.Example `name-of-the-service-account@my-great-project-1234560.iam.gserviceaccount.com` |
| `client_id`required | `string` | The client id.Example `378463746364563353673` |
| `auth_uri`required | `string` | The authorization URI.Example `https://accounts.google.com/o/oauth2/auth` |
| `token_uri`required | `string` | The token URI.Example `https://oauth2.googleapis.com/token` |
| `auth_provider_x509_cert_url`required | `string` | The URL of the public x509 certificate provider.Example `https://www.googleapis.com/oauth2/v1/certs` |
| `client_x509_cert_url`required | `string` | The RL of the public x509 certificate.Example `https://www.googleapis.com/robot/v1/metadata/x509/name-of-the-service-account%40my-great-project-1234560.iam.gserviceaccount.com` |
##### Response `200``application/json`
2 fields
Ok.
| Field | Type | Description |
| --- | --- | --- |
| `code` | `string` | Status code. |
| `message` | `string` | The message. |
##### Response `400``application/json`
1 fields
Bad Request.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Bad Request error. |
| `code`required | `one of` | Bad Request |
| `message`required | `string` | Error description. |
##### Response `401``application/json`
1 fields
Unauthorized.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Unauthorized error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `403``application/json`
2 fields
Forbidden
| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL. |
| `message` | `string` | Error message. |
##### Response `408``application/json`
1 fields
Request Timeout.
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Timeout error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `409``application/json`
1 fields
Conflict
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `500``application/json`
1 fields
Internal Server Error
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `501``application/json`
1 fields
Not Implemented
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `502``application/json`
1 fields
Bad Gateway
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
##### Response `503``application/json`
1 fields
Service Unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `object` | Conflict error. |
| `code`required | `string` | Error name. |
| `message`required | `string` | Error description. |
`POST` `/batch-process-document`
#### Process Batch
`new-batch`
Long-running operation endpoint to batch process many documents.
##### Request
application/json Copy An example of a batch request. Presigned URLs shown here are just examples, you need to provide valid and active Presigned URLs when making the request.
```
{
"urls": [
"https://somebucketname.s3.us-east-1.amazonaws.com/test.pdf?X-Amz-Algorithm=&X-Amz-Credential=%2F20180210%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=&X-Amz-Expires=1800&X-Amz-Signature=