Claude API integration: how to connect Claude to your business systems

Less model and more plumbing than most people expect. A Claude API integration is a piece of your own software that gathers some business data, sends it to Claude with instructions, gets back a structured answer, checks it, and does something with it: fills a review screen, drafts a reply, proposes a change to a record. The model call itself is a few lines. The rest (where the key lives, what data is allowed in, how the answer is checked, who approves the write, what happens at a rate limit, what gets logged) is where the engineering goes, and where integrations succeed or fail.

To be clear about what this page is for. If you want someone to build this for you, our Claude API integration consultant page sets out how we do that and what it costs. If you have not yet decided between Claude and another provider, our Claude API vs OpenAI API article sets out what to compare. This guide is the layer underneath both: the architecture, the build order and the failure modes, written so your own developers could follow it.

What we draw on. Four case studies on this site list Claude in their stack: a trading group's ERP whose invoice scanner uses Claude as one of two model providers, an estimating assistant (a working demo), a solar installer's operating system with an in-app copilot, and a marketing platform. Their write-ups describe what the model may and may not do. They do not state model versions, volumes or accuracy figures, so neither does this guide. Anthropic facts come from its documentation, read on 21 October 2026 and listed under Sources. We are an independent studio, not an Anthropic partner, and nothing here is endorsed by Anthropic.

Eight parts, most of which you would build for any integration. The Claude-specific part is one request to Anthropic's Messages API. Tool use and structured output are options on that same request, not separate products, so the architecture is the same whether the model is classifying an email or calling tools over your CRM.

The shape that recurs across our builds is that the model proposes and the surrounding code decides. On the estimating assistant the model names the parts, chosen only from candidates drawn from the price book, and a deterministic function sets every price. On the marketing platform the model classifies and summarises news items, but the link and the title come from the feed, so it has no way to invent a source. Draw that line for your own job before writing a prompt: which values the model may produce, and which must come from your data.

On a server you control, never in the browser and never in a mobile app bundle. A key shipped to a browser can be read by anyone who opens the developer tools, and from then on your bill and your rate limits belong to them. Anthropic's authentication documentation positions static API keys for servers where you control secret storage, tells you to keep them in a secrets manager, rotate them and set an expiry, and describes a separate attestation mechanism for iOS and macOS apps that call the API from the device. Its data-retention page tells organisations under zero data retention, for whom cross-origin browser calls are not supported, to route browser requests through a backend proxy. The safe default for everyone else is the same.

• Use a key that belongs to a workload, not a person. Anthropic describes personal keys, which stop working when that person leaves the organisation, and service account keys for shared or production workloads. For workloads on AWS, Google Cloud or Azure it documents workload identity federation, which swaps static keys for short-lived tokens.
• Separate environments with workspaces. Anthropic suggests workspaces to separate environments and control spend by use case, and limits can be set per workspace, so a runaway test cannot eat production's capacity.
• Make the boundary something the build enforces. On the fleet-order automation we built (not a Claude build, but the same problem with an account-wide monday.com token), the module that talks to the credential-holding service imports a server-only marker, so a browser component reaching for it fails the build instead of relying on a reviewer to notice.
• Apply the user's permissions before the prompt, not after the answer. If a sales rep cannot see margin in the CRM, margin should not be in the context you send on their behalf. The model cannot leak what it was never given.

In: the fields the task needs, labelled, and nothing else. Out: a structured proposal your code can check. Resist sending whole records or whole mailboxes because the context window is large. Every extra field is cost, a place for the model to pick up the wrong value, and more data leaving your systems. The estimating assistant cuts payment terms and conditions out of a proposal before the model sees it, because the extraction does not need them.

Documents and images go in directly. The trading ERP's scanner works from a photograph of a supplier invoice. Anthropic's Messages API caps a request at 32 MB, so very large files need splitting or a different route, and the comparison article covers when retrieval beats a bigger prompt.

What comes back should be the smallest structure that lets a person or a program act: identifiers that already exist in your system, values copied from the source, a short reason, and a flag when the model is unsure. Ask the model to copy numbers, not compute them. The estimating assistant tells the model to copy figures exactly and never calculate, then does every sum in code, which is how a document that does not reconcile gets flagged instead of saved.

Through tools you define and your code executes. You describe each tool (a name, a description and a JSON schema for its inputs) in the request. When Claude decides to use one, the response stops with a tool_use reason and one or more structured calls. Your application runs the operation, sends the result back in a tool_result block, and Claude continues. Anthropic's documentation calls these client tools, as distinct from server tools such as web search that run on Anthropic's infrastructure. For a business integration the distinction matters: with a client tool, the permission check, the database query and the write all happen in code you own.

Designing the tools

• Write long descriptions. Anthropic's guidance calls detailed descriptions by far the most important factor in tool performance and suggests at least three or four sentences per tool: what it does, when to use it and when not, what each parameter means, and what it does not return.
• Keep the surface small. Anthropic recommends consolidating related operations into fewer tools and prefixing each name with the system it touches as the set grows. We add one rule of our own: never put a read and a write in the same tool, because they need different permission checks and only one of them can hurt you.
• Return high-signal results: stable identifiers and only the fields the next step needs. A tool that dumps a whole customer record wastes context and invites the model to quote the wrong field.
• Report failures as errors the model can act on. Anthropic's documentation describes an is_error flag on a tool result and recommends instructive messages (what went wrong and what to try next) over a bare 'failed'.
• Mark tools strict where the inputs must match the schema exactly. Anthropic documents strict tool use as guaranteeing schema-valid tool inputs.

Reading versus writing

Give read tools freely and write tools reluctantly. A write tool should create a proposal (a draft order, a suggested field change, an unsent email) rather than change the record, and it should call the same business logic as your existing API, so validation rules, permissions and the audit trail still apply. That is how the copilot on the solar operating system is built: it runs a tool-use loop over the live CRM, its writes go through the same business logic as the REST API and sit behind a flag, and the public website chatbot on the same system gets exactly one tool, which captures a lead. Tools that send, pay or delete come last, if at all.

Treat everything a tool returns as untrusted. A CRM note, an inbound email or a supplier PDF can contain text that reads like an instruction. Anthropic's tool-use documentation warns about exactly this and says to keep such content inside tool_result blocks rather than in the system prompt. The structural defence is that the step reading untrusted content has no tool that can send, pay or delete. Our article on securing AI agents covers the layers in full.

Ask for it with a schema, then check it as if you had not. Anthropic documents two features under the name structured outputs: JSON outputs, which constrain the response to a JSON schema you supply in the request, and strict tool use, which guarantees tool inputs match the tool's schema. Both use constrained decoding, which removes most parsing failures. The documentation is also candid about where the guarantee stops, and each of those edges needs code on your side.

Then the checks that no schema can do, because a schema checks shape and not truth. A supplier name must match a supplier you hold, or be offered as a near match rather than created as a duplicate. Line items must add up to the stated total. A part number must exist in the price book. An email recipient must be on an allowlist. On the estimating assistant, code trusts the extracted bill of materials only if every parent equals the sum of its children, and rebuilds the tree from the sums when it does not. Our document extraction article works through the arithmetic check with an example.

One practical consequence of current models. Anthropic's documentation says some current models reject forced tool choice (making the model call a named tool) with a 400 error, and points to strict tools with the default automatic choice, or JSON outputs, instead. If an older integration used a forced tool call as a way to get JSON back, switch it to JSON outputs before you change model.

Cost follows tokens in and out, the model tier and how often you repeat yourself. Four levers do most of the work, and all four are design decisions rather than settings you add later. Our AI integration cost article covers budgeting and the costs that are not tokens; this is the engineering side.

Prompt caching for the part that repeats

Instructions, schemas, tool definitions and reference material that go out on every call can be cached. Anthropic's documentation says the cache matches on the prompt prefix in a fixed order (tools, then system prompt, then messages), that cache reads cost a fraction of the base input price, that the default cache lifetime is five minutes refreshed each time it is used, with a one-hour option at extra cost, and that prompts below a model-dependent minimum length are not cached at all, with no error. For most models, cached reads also do not count toward the input-tokens-per-minute rate limit, so caching raises throughput as well as cutting cost.

The design consequence is ordering. Put everything stable first and everything that varies (the document, the question, today's date) last. A timestamp at the top of the system prompt, a tool list assembled in a different order on each call or a per-request ID in the instructions will quietly defeat the cache. Check the cache_read_input_tokens figure in the response usage: if it stays at zero across repeated calls, something in the prefix is changing.

Batch for work that can wait

Anthropic's Message Batches API processes requests asynchronously at half the standard cost. Its documentation says most batches finish within an hour, that a batch expires if not complete within 24 hours, and that results can come back in any order, so each request carries an ID you match on. It suits a back catalogue of documents, an overnight enrichment run or an evaluation run. It does not suit a person waiting at a screen. Note the data-handling difference below: batch jobs are stored, so batch is not covered by zero data retention.

A model tier per route

Anthropic's models overview describes its smallest current tier as built for high-volume, latency-sensitive tasks such as classification, extraction and routing, and suggests its Opus tier as the place to start when unsure. Current models also take an effort setting that trades thoroughness against tokens. Our practice: prove the job is possible on the stronger tier with your evaluation set, then try each route on a cheaper tier or a lower effort and keep the change only where the scores hold. Routing an email to the right queue rarely needs the same model as reading a creased photograph of an invoice.

Budgets, deduplication and a ceiling

Cap tokens and tool-call steps per run, hash documents before calling the model so a double trigger is not a double charge, and log usage per workflow so a rise has a name. Anthropic lets an organisation set its own spend limit below its tier's cap, and limits per workspace. Decide before launch who is told when one is reached, because the pipeline will stop.

Plan for limits as normal operating conditions. Anthropic's rate-limit documentation says limits are set per organisation by usage tier, that new organisations may start in a lower evaluation tier, that limits are measured in requests, input tokens and output tokens per minute, and that capacity refills continuously, so a short burst can trip a limit even when the average is well inside it. It also describes acceleration limits for organisations whose usage rises sharply, and recommends ramping traffic up gradually. Find out your tier before the launch date, not on it.

Not every error deserves a retry, and the costliest mistake we look for when reviewing an integration is a loop that retries the one that never clears.

Anthropic's official SDKs retry connection errors, rate limits and server errors with exponential back-off, twice by default, honouring retry-after when present. Know that this happens, so your own retry layer does not multiply it. For long generations the documentation recommends streaming or the batch interface, and says the SDKs check that a non-streaming request is not expected to run past ten minutes.

Two things retries cannot fix. First, idempotency: if a call times out after the model answered and your code wrote a proposal, a blind retry writes a second one. Key every job on a document hash or source ID so a repeat updates rather than duplicates. Second, a single point of failure. The trading ERP's scanner holds several keys per provider, advances on rate-limit, quota or authentication failures, then falls through to a second provider, and says so plainly when no keys are configured. Limits are set per organisation, so extra keys inside one account may not add capacity; their value is surviving a revoked or misconfigured key.

At every step that writes to the books, sends outside the company or cannot be quietly reversed next week. The model proposes; a confirmation writes. On the trading ERP, photographing an invoice writes nothing: the extraction appears for review, and only the confirmation creates the purchase invoice and moves stock, cost prices and the supplier balance. On the solar operating system, a model extracts who said they would do what by when from a meeting transcript, and nothing becomes an action until a person confirms it. On the marketing platform, drafts land in an approval queue and approval is blocked while unverified funding or statistics claims remain.

• Show the proposal beside its evidence: the source document, the record it would change, and the before and after values.
• Let the reviewer correct, not just accept or reject, and store the correction. Corrections are your best source of new evaluation cases.
• Track how often reviewers change or reject proposals. A confirmation that is always clicked through is not a control.
• Introduce writes in shadow mode first. The fleet-order automation (again, not a Claude build) shipped its allocation layer behind a shadow-mode flag that logged what it would have done beside the manual process; that is the safest way to introduce any model step that acts.
• Automate approval only for narrow, low-risk, measured cases, and only once the evaluation set and the override rate say you can.

Log enough to answer 'why did it do that?' months later, and keep an evaluation set so a change is a measurement rather than a guess.

• Per call: the request ID (Anthropic returns one on every response, in a request-id header, and asks for it in support cases), the model ID, the prompt version, a hash of the input, the stop reason, and token usage including the cache fields.
• Per job: the validation result, the tools called with their arguments and results, the proposal, who confirmed or corrected it, and the final write.
• Where: beside your audit trail, not instead of it. On the trading ERP every write passes through one data-access layer that appends a field-level change to a table staff can insert into but never update. The model call belongs next to that entry.
• Alerts: spend per workflow, the spend-cap error, validation failure rate, refusal rate and reviewer override rate. The account total tells you something moved; per-workflow figures tell you what.

The evaluation set is a few dozen real inputs, the worst ones included, with the right answer written down. Anthropic's guidance on building evaluations starts from measurable success criteria, says evaluations should mirror your real task distribution including edge cases, and favours more automatically graded cases over fewer hand-graded ones. Run it on every prompt change, every model change and every deprecation notice. The estimating assistant goes further and holds one real job out of its library entirely, comparing each draft with the quote that was actually sent.

Plan for model retirement from day one. Anthropic's documentation says every model ID is a pinned snapshot, that publicly released models get at least 60 days' notice before retirement, that requests to a retired model fail, and that deprecated models are likely to be less reliable than active ones. Keep the model ID in configuration so the change is small, but do not treat it as a configuration flip: the request surface moves between generations (Anthropic's deprecations page lists sampling parameters that newer models reject at non-default values, and its errors page lists prefilled assistant messages and forced tool choice among the requests newer models refuse). A model upgrade is a code change, tested against the evaluation set.

Read the retention terms for the exact endpoints and features you use, because they differ by feature. As of 21 October 2026, Anthropic's API and data retention page says the following for the Claude API.

• Retained data is never used for model training without your express permission.
• Conversation content (prompts and outputs) is not retained by default. The exception is a set of models the page calls Covered Models, among Anthropic's most capable, which require 30-day retention. Check whether the model you plan to use is on that list.
• Zero data retention is available per organisation on request through Anthropic's sales team. It does not cover the Console and its playground, and several features are not eligible because they store data by design: the Batch API (29-day retention), the Files API (kept until deleted or expired) and code execution (container data up to 30 days).
• Flagged content and legal holds are retained whatever the arrangement.
• With structured outputs, the JSON schema itself is cached for up to 24 hours since last use, and the documentation says protected health information must not be put in a schema definition.
• HIPAA-ready access is available with a signed business associate agreement, for eligible features.
• On Amazon Bedrock and Google Cloud, the cloud provider is the data processor and its own terms apply.
• Prompt caches are isolated between organisations, and per workspace on the Claude API.

Which gives a short procurement checklist: which model, which endpoints (batch and files change the picture), which cloud, whether you need zero retention or a BAA, and where processing happens. Then apply the control you hold yourself, which is scope. Send fields rather than records, redact what the task does not need, and keep source documents in your own private storage beside the record they produced. The comparison article covers the questions to put to any provider in writing.

In the order that lets you stop early. Each step either proves the next is worth doing or tells you to use something simpler.

1. 01Write down the decision the model makes. If the rule fits on one side of paper, it is code, not a prompt, and you can stop here.
2. 02Collect the evaluation set: a few dozen real inputs, the ugly ones included, each with the correct answer written down by the person who does the job today.
3. 03Prototype the single model call in a script against that set, with an output schema, on a strong tier. Score it field by field. If it cannot do the job here, no amount of plumbing will help.
4. 04Move the call behind your server: key in a secrets manager, a workspace per environment, a spend limit, and the user's permissions applied in the context builder.
5. 05Build the validation layer: schema, arithmetic, identity against your records, stop-reason checks.
6. 06Build the review screen and the write-back through your existing business logic. Run in shadow mode beside the manual process and compare.
7. 07Add read-only tools only if the model genuinely needs to look things up mid-task. Add write tools as proposal-makers, one at a time, each with a named control.
8. 08Tune cost: order the prompt for caching, move non-urgent volume to batch, and step each route down a model tier or an effort level where the evaluation scores hold.
9. 09Wire up logging and alerts, and write the runbook for a spend-cap stop, a provider outage and a model retirement notice.
10. 10Go live on a narrow slice (one document type, one team) and widen on evidence: the override rate and the evaluation scores, not enthusiasm.

In our experience most of the time goes on steps 5, 6 and 9, not on prompting, which is why we quote against your documents rather than a feature list.

More often than the current enthusiasm suggests, and saying so is part of the job.

• When the rule can be written down. An order value over a threshold, a supplier on an approved list, a date inside a window: an if-statement is instant, free per run, identical every time and explainable to an auditor.
• When the data already arrives structured. An API, a CSV or an EDI feed has nothing for a model to read. A Make or n8n scenario, or a few lines of code, will move it for less.
• When nobody will read the output and a wrong answer cannot be undone. A model should not be the last step before money moves or a customer is contacted, unreviewed.
• When the answer must be identical every time for compliance. Models are not deterministic in the way a calculation is. Use the model to propose and code to decide, or do not use it.
• When the product you already pay for does it. If your accounting or CRM package offers capture or drafting that handles your documents, test that first.
• When the volume is tiny. Ten documents a week that a person handles in a few minutes do not justify a pipeline, an evaluation set and a monitoring routine.

When the job does fit (unstructured input, an output a person can check, enough volume to matter) the pattern above holds whichever model you use. If you would like us to build it, the Claude API integration consultant page sets out how we work and what moves the price. If you are still deciding whether you need an agent or a workflow, our article on AI agents for operations is the place to start.