> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/docs/issuance/flow-1/trigger-by-user-for-equs-wallet-pull-tx_code-delivery/method-1-api.md).

# Method 1: API

Create the Offer, set pull delivery, and share the link from your own front end

Your back end orchestrates the whole thing: create the Offer, tell the platform the wallet will fetch the code, then put the link in front of the Holder yourself.

**Before you start** you need an [Issuer and VC Schema](/docs/issuance/configuration-issuer-and-vc-schema.md), and your identity provider registered with the platform - see [Bring Your Own IdP](/docs/onboarding/bring-your-own-idp.md). `pull` delivery only works for a Holder signed in to an EQUS Wallet as one of your users.

### 1. Create the Offer

`POST /api/v1/oid4vci/offers`, carrying the Schema **version** you are issuing against, the Issuer doing the signing, your own user ID for the Holder, and the claim values.

No `autoIssuance` here - adding it would settle delivery in this call and skip step 2 entirely.

{% hint style="info" icon="rectangle-api" %}
All calls mentioned on this page are on the [Integration API](https://docs.toolkit.equs.ai/docs/issuance/flow-1/trigger-by-user-for-equs-wallet-pull-tx_code-delivery/pages/MvAvsnLQU3ER2hOIIDU2#id-2.4.1-apis).
{% endhint %}

## Create Credential Offer

> Create Credential Offer with provided claims based on VC Schema Version and Issuer. Optionally, intended User ID can be provided

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vci","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateCredentialOfferRequest":{"type":"object","properties":{"vcSchemaVersionId":{"type":"string","description":"VC schema version unique ID"},"claims":{"type":"object","description":"Claims to include in the issued credential."},"issuerId":{"type":"string","description":"Issuer unique ID"},"userId":{"type":"string","description":"User unique ID"},"autoIssuance":{"description":"When provided, the offer is automatically bound and issued to the given holder.","allOf":[{"$ref":"#/components/schemas/AutoIssuance"}]}},"required":["vcSchemaVersionId","claims","issuerId","userId"]},"AutoIssuance":{"type":"object","properties":{"email":{"type":"string","description":"Email address the offer notification is sent to when auto-issuance completes."}},"required":["email"]},"CreateCredentialOfferResponse":{"type":"object","properties":{"params":{"description":"OID4VCI credential offer parameters.","allOf":[{"$ref":"#/components/schemas/OfferParams"}]},"byValue":{"type":"string","description":"Credential offer deep link encoding the offer payload by value."},"byReference":{"type":"string","description":"Credential offer deep link referencing the offer by URI."},"txCode":{"type":"string","description":"Transaction code the holder must input to accept the offer."},"uriId":{"type":"string","description":"Credential offer URI unique ID"}},"required":["params","byValue","byReference","txCode","uriId"]},"OfferParams":{"type":"object","properties":{"credential_issuer":{"type":"string","description":"Base URL identifying the credential issuer."},"credential_configuration_ids":{"description":"Identifiers of the credential configurations offered.","type":"array","items":{"type":"string"}},"grants":{"description":"Grants supported for redeeming this credential offer.","allOf":[{"$ref":"#/components/schemas/OfferGrants"}]}},"required":["credential_issuer","credential_configuration_ids"]},"OfferGrants":{"type":"object","properties":{"urn:ietf:params:oauth:grant-type:pre-authorized_code":{"description":"Pre-authorized code grant details.","allOf":[{"$ref":"#/components/schemas/OfferGrantPreAuth"}]}}},"OfferGrantPreAuth":{"type":"object","properties":{"pre-authorized_code":{"type":"string","description":"Pre-authorized code the wallet exchanges for an access token."},"tx_code":{"description":"Transaction code requirements for the pre-authorized code grant.","allOf":[{"$ref":"#/components/schemas/PreAuthTxCode"}]},"authorization_server":{"type":"string","description":"Identifier of the authorization server issuing the pre-authorized code grant."}},"required":["pre-authorized_code"]},"PreAuthTxCode":{"type":"object","properties":{"input_mode":{"type":"string","description":"Format expected for the user-entered transaction code."},"length":{"type":"number","description":"Expected length of the transaction code."},"description":{"type":"string","description":"Human-readable guidance shown to the user for entering the transaction code."}}}}},"paths":{"/api/v1/oid4vci/offers":{"post":{"description":"Create Credential Offer with provided claims based on VC Schema Version and Issuer. Optionally, intended User ID can be provided","operationId":"Oid4VciController_createCredentialOffer_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCredentialOfferRequest"}}}},"responses":{"200":{"description":"When Offer is created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCredentialOfferResponse"}}}},"400":{"description":"- When no VC Schema Version exists with such id.\n- When no Issuer exists with such id.\n- When the Credentials don't match the schema."}},"summary":"Create Credential Offer","tags":["Oid4Vci"]}}}}
```

Keep `uriId` to address the Offer in step 2, and `byReference` to share it in step 3.

### 2. Set `tx_code` delivery to `pull`

`POST /api/v1/oid4vci/offers/{uriId}/delivery`. Send the same `userId` you created the Offer with.

## Deliver Tx Code

> Delivers the tx-code corresponding to the Offer

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vci","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"DeliverTxCodeRequest":{"type":"object","properties":{"delivery":{"description":"Delivery channel used to send the tx-code to the holder. Shape depends on the discriminating \"method\" field.","oneOf":[{"$ref":"#/components/schemas/PullDelivery"},{"$ref":"#/components/schemas/EmailDelivery"}]}},"required":["delivery"]},"PullDelivery":{"type":"object","properties":{"method":{"enum":["email","pull"],"type":"string","description":"Discriminator identifying this delivery as a pull delivery."},"userId":{"type":"string","description":"User unique ID"}},"required":["method","userId"]},"EmailDelivery":{"type":"object","properties":{"method":{"enum":["email","pull"],"type":"string","description":"Discriminator identifying this delivery as an email delivery."},"email":{"type":"string","format":"email","description":"Email address the tx-code is sent to."}},"required":["method","email"]},"DeliverTxCodeResponse":{"type":"object","properties":{"txCodeFetchUrl":{"type":"object","description":"The url from which the tx-code can be fetched. It is only defined when the delivery type is pull"},"txCodeResendUrl":{"type":"object","description":"The url from which the tx-code can be resent. It is only defined when the delivery type is email"},"txCodeResendCooldown":{"type":"number","description":"Number of seconds to wait before the tx-code can be resent again."}},"required":["txCodeResendCooldown"]}}},"paths":{"/api/v1/oid4vci/offers/{id}/delivery":{"post":{"description":"Delivers the tx-code corresponding to the Offer","operationId":"Oid4VciController_delivery_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Credential offer unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverTxCodeRequest"}}}},"responses":{"200":{"description":"When tx-code is delivered successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverTxCodeResponse"}}}},"400":{"description":"When the Offer was already delivered"},"404":{"description":"When the Offer is not found"}},"summary":"Deliver Tx Code","tags":["Oid4Vci"]}}}}
```

You get back `txCodeFetchUrl` - the address the wallet uses to collect the code on the Holder's behalf. You don't call it, and you don't show the code to anyone.

### 3. Share the Offer

Put `byReference` in front of the Holder:

* **Mobile wallet** - render it as a QR code to scan.
* **Web wallet** - open the link directly.

The Offer also appears in the Holder's **Pending Offers** by itself, so the link is a convenience rather than the only way in.

### 4. Track the result

See [Issuance Results](/docs/issuance/issuance-results.md), which is also where the revocation handle lives.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/docs/issuance/flow-1/trigger-by-user-for-equs-wallet-pull-tx_code-delivery/method-1-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.