🛠️Tag API Resources

Legitimate allows agencies and developers to create entirely custom digital experiences on the Legitimate platform for a given set of tags using our APIs.

Direct access to our APIs require a yearly subscription to our hosted API services. Different plans are available depending on the number of tags supported, API usage limits, custom domains for endpoints, and CORS domain allowlists.

API request and response interfaces are subject to change. Changes will be versioned. All customers will be notified of changes and provided upgrade instructions.

Standard Resources

All standard tag resources can be accessed from our external API gateway domain. This domain can be accessed without authentication tokens, API keys, or CORS restrictions.

A fair usage rate limit per API endpoint and per client applies. Contact us to request an API key if you expect high usage rates.

https://ext-api.legitimate.tech

Tags

Verify

POST /v1/tags/verify

Verifies the tag's authenticity via the unique uid, ctr, and cmac generated by each tap of the LGT Tag. This API will only return the success response the first time it is called with the correct tag information. Subsequent calls will return the HTTP status 422 and the error message has expired.

request_body: {
  uid: string,
  ctr: string,
  cmac: string
}
success_response: {
  uid: tag_uuid,
  verified: true,
  nft_chain_id: number, // optional
  nft_contract_address: string, // optional
  nft_token_id: number, // optional
  name: string, // optional
  description: string, // optional
  image_url: string, // optional
  animation_url: string, // optional
  sku_id: number,
  serial_number: number, // optionally set during tag programming or activation
}
error_response: { // status 4xx
  errors: {
    cmac: "has expired" | "is invalid",
    tag: ["could not be found"]
  }
}

Claim

POST /v1/tags/claim

Transfers the NFT associated with the tag to the specified wallet address. The uid, cmac, and ctr must be from the latest successful verify attempt. All previous verifications are invalid to prevent users with old links from claiming.

request_body: {
  uid: string,
  ctr: string,
  cmac: string,
  walletAddress: string
}
success_response: {
  hash: string  // hash of on-chain transaction, tx may not be confirmed yet
}
error_response: { // status 4xx
  error: "This tag has not been enabled for claiming." |
    "This NFT has already been claimed and is no longer held by Legitimate." |
    "Session expired. Please tap the Legitimate Tag and try again."
}

Recover

POST /v1/tags/recover

Recovers the NFT back to the Legitimate wallet to reset the ownership state of the NFT. The uuid, cmac, and ctr must be from the latest verification. All previous verifications are invalid to prevent users with old links from recovering.

After recovery, the NFT can be claimed again with the claim API.

request_body: {
  uid: string,
  ctr: string,
  cmac: string
}
success_response: {
  hash: string // hash of on-chain transaction, tx may not be confirmed yet
}
error_response: { // status 4xx
  error: "Unauthorized" |
    "Ownership reset has not been enabled for contract ${contract.address} by ${walletAddress}." |
    "Transaction failed with message: ${error.message}"
}

Verifications

Verifications for a tag

GET /v1/verifications/{uid}

Lists all the successful verification attempts associated with a tag.

success_response: {
  verifications: [
    {
      created_at: '2023-10-25T09:13:31+00:00',
      verify_type: 'programming_qc' | 'manufacturer_qc' | 'user_view' | string
      uid: "AABBCCDDEEFF00",
      tamper: false,
      counter: 5,
      city: 'Aobadai',
      region: 'Tokyo',
      country: 'Japan',
      latitude: 35.6509,
      longitude: 139.6943
    }
  ]
}
error_response: { // status 4xx
  error: {
    tag: ["could not be found"]
  }
}