The Flowcode API is frequently utilized for generating a vast number of codes. Although the Flowcode.com platform allows for creating codes in bulk by uploading a CSV file, it is beneficial for certain scenarios and is limited to 1000 codes at a time. Other use cases require a more immediate integration or entail the generation of codes on a much larger scale. To address these requirements, our newly introduced endpoints for the programmatic creation of codes at scale offer a few possibilities.

"Bulk Generate 1:1 Codes" refers to generating multiple unique codes in bulk on the Flowcode Platform, where each code is mapped to a specific action or entity. The 1:1 ratio means that each code is associated with one particular action or entity and is unique to that particular association. Bulk generating 1:1 codes is a way to efficiently create many unique codes and manage them effectively for specific purposes.

Prerequisites

1. Know what code design, aka studio_config_id, you are using
2. Know what file type your system wants

We currently support the following file types:

• JPG
• PNG
• SVG
• PDF
• TIFF
3. Know the scan destination of each code OR have a plan to bulk update the destination before the codes are in the world

There are various scan destination types that we support

Destination Type	Protocol	Required Params	Optional Params	Example
SMS	sms:	phone number	body	sms:1234567890;?&body=hello%20world
PHONE	tel:	phone number	N/A	tel:1234567890
EMAIL	mailto:	email address	subject, body	mailto:example@email.com?subject=test&body=hello%20world
VENMO	venmo://	recipient	amount, note	venmo://paycharge?txn=pay&recipient=john-doe&amount=10&note=testing
WIFI	WIFI:	SSID (S), security (T), hidden (H)	password (P)	WIFI:T:WPA;S:my-network;P:p@ssw0rd;H:true;

If you are not yet ready to set a scan destination, but want to generate the codes (say you want to get the print process started), our dynamic codes allow you to update the scan destination after creation. You should have a plan in place for this and allocate enough time to complete the update prior to the codes going live in the world. If you need assistance our team can help update the scan destination of your codes, but understand the turnaround time associated with this; we also provide a self-service way of updating code scan destination via the update code endpoint of our API.
4. Check your inventory

In the context of a high-scale system, a recommended approach is to establish a Flowcode Inventory. This entails implementing a daily routine to replenish the inventory, enabling direct access to a reserve of codes for large campaigns or projects without relying on the API. As the inventory's intended use is not predetermined, bulk update endpoints, as previously described, may be necessary. This strategy can effectively save time and streamline code management processes.

Option 1: Calling Create Code Iteratively

This approach involves calling the create code endpoint once per code that needs to be created. While not the most efficient, it is the preferred method until we introduce a new bulk create endpoint in production. Let's see a code snippet of what this might look like in practice:

      
        import json
        import requests

        url = "https://gateway.flowcode.com/v4/codes"
        codes_to_create = 2000
        for i in range(codes_to_create):
          # create payload for POST request
          payload = {
            "destination": {
              "destination_type": "URL",
              "redirect_value": {
                "url": "https://mysite.com"
              }
            },
            "studio_config_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", # your studio_config_id
            "folder_id": 12345, # we recommend bulk creating into a folder for better organization
            "code_name": f"code_{i+1}", # code_name must be unique since we are placing in a folder
          }
          headers = {"apikey": {your_api_key}, "Content-Type": "application/json"}

          response = requests.post(url, data=json.dumps(payload), headers=headers)
          if response.status_code != 201:
            raise Exception(response.text)
          percentage_complete = round(((i+1)/codes_to_create)*100, 2)
          print(f"{percentage_complete}% of codes created")
      
    

The code snippet performs the following tasks:

1. Defines the URL of the endpoint for creating codes.
2. Specifies the number of codes to be created, which is 2000.
3. Uses a loop to iterate through each code to be created.
4. Creates a payload for a POST request with the necessary code details, such as the destination and unique code name, and includes the required authentication headers.
5. Sends the POST request to the specified endpoint using the requests module.
6. Checks the response status code to ensure the code creation was successful; if not, an exception is raised.
7. Calculates and prints the percentage of codes that have been created as the loop continues to iterate until all codes have been created.

This code snippet generates 2000 unique codes by sending 2000 separate requests to the Flowcode API endpoint. The code names and destination URLs can be customized to fit your specific needs.

Option 2: Calling Bulk Create

The more efficient and preferred method for bulk-creating codes would involve utilizing one of our new bulk endpoints. Instead of creating individual API calls for each code, all the codes can be created in a single API call within a certain limit defined by the platform. The main difference between this approach and the previous one is that the entire Bulk payload will be built without API calls being made during the loop. After the payload for all the codes to be created has been built, a single API call can be made to create all the codes in Bulk. This approach will considerably reduce the number of API calls required and improve the efficiency of the process. Here is a code snippet exemplifying how this approach may be implemented:

      
        import json
        import requests
        import time

        url = "https://gateway.flowcode.com/v4/codes/bulk"
        codes_to_create = 2000
        bulk_payload = []
        for i in range(codes_to_create):
          # create payload and add to bulk_payload
          payload = {
            "destination": {
              "destination_type": "URL",
              "redirect_value": {
                "url": "https://mysite.com"
              }
            },
            "studio_config_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", # your studio_config_id
            "folder_id": 12345, # we recommend bulk creating into a folder for better organization
            "code_name": f"code_{i+1}", # code_name must be unique since we are placing in a folder
          }
          bulk_payload.append(payload)

        headers = {"apikey": {your_api_key}, "Content-Type": "application/json"}
        response = requests.post(url, data=json.dumps(payload), headers=headers)

        # If creating more than 50 codes in bulk, you will receive a 202 (Accepted) status code
        # If creating 50 codes or less in bulk, you will receive a 201 status code
        if response.status_code != 202:
          raise Exception(response.text)
        
        # NOTE: The below is only applicable if you are creating more than 50 codes, in which case code creation
        is performed asynchronously. If creating 50 or less, the creation is synchronous and you will receive
        JSON of the code details.

        # Take task_id and periodically check status of the creation
        task_id = response.json()["task_id"]
        status_endpoint = "https://gateway.flowcode.com/v4/codes/bulk/:task_id/status"
        response = requests.get(url, headers=headers).json()
        status = response["status"]
        message = response["message"]
        while status != "SUCCESS" and status != "FAILURE":
            time.sleep(10) # sleep for some time between checks
            response = requests.get(url, headers=headers).json()
            status = response["status"]
            message = response["message"]
        
        if status == "FAILURE":
            print(f"Creation failed with error: {message}")
            raise Exception(message)
        else:
            print("Bulk Creation Complete!")
      
    

The code snippet performs the following tasks:

1. Defines the URL of the endpoint for bulk creating codes.
2. Sets the number of codes to create to 2000.
3. Creates an empty array called bulk_payload.
4. Enters a loop that iterates codes_to_create times, where:
   • Creates an object called payload containing the data for a single code.
   • Appends the payload object to the bulk_payload array.
5. Sets the headers of the API request to include the API key and the Content-Type (application/json).
6. Makes a POST request to the API endpoint URL with the bulk_payload data using the requests module.
7. Retrieves the task_id of the bulk creation and repeatedly calls the bulk status endpoint until a terminal state is reached.
8. If the task was successful, print a message that the bulk creation is complete, otherwise print the failure message.

---