{
  "openapi": "3.0.1",
  "info": {
    "title": "Overview",
    "description": "Locations are subsets of divisions, which are subsets of your enterprise. Each division can contain multiple locations. At least one division must already exist in order to create a location.\n\n**Divisions and locations allow you to:**\n\n- Assign users to a specific location\n- Give users permission to perform admin tasks for specific divisions or locations\n- Assign different carrier accounts to certain divisions or locations\n- Allow cost accounts to be used by only specified divisions or locations\n- View reporting data for individual divisions or locations (requires Analytics subscription)\n- Give users permission to view reporting data for specific divisions or locations (requires Analytics subscription)\n",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://api-sandbox.sendpro360.pitneybowes.com/locationmgmt",
      "description": "Sandbox Server for Location Management API"
    },
    {
      "url": "https://api.sendpro360.pitneybowes.com/locationmgmt",
      "description": "Production Server for Location Management (uses live data)"
    }
  ],
  "tags": [
    {
      "name": "Location Management",
      "description": "APIs return the details of divisions and locations associated with the developer."
    }
  ],
  "paths": {
    "/api/v1/divisions": {
      "get": {
        "tags": [
          "Location Management"
        ],
        "summary": "Get Divisions Details",
        "description": "This operation provides the divisions details.",
        "operationId": "getDivisions",
        "parameters": [
          {
            "name": "X-PB-Developer-Partner-ID",
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "page number",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "size of records",
            "required": false,
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Divisions Get Successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetDivisionsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api/v1/locations": {
      "get": {
        "tags": [
          "Location Management"
        ],
        "summary": "Get Locations Details",
        "description": "This operation provides the location details with the subscription.",
        "operationId": "getLocations",
        "parameters": [
          {
            "name": "X-PB-Developer-Partner-ID",
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "divisionID",
            "in": "query",
            "description": "It specifies the division id. If provided it will only show the location details under this division.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "page number",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "size of records",
            "required": false,
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Locations Get Successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetLocationsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "GetLocationsResponse": {
        "type": "object",
        "properties": {
          "pageInfo": {
            "type": "object",
            "description": "Pagination details",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total number records displayed",
                "example": 1
              },
              "pages": {
                "type": "number",
                "description": "Total pages",
                "example": 1
              },
              "page": {
                "type": "number",
                "description": "current page",
                "example": 10
              }
            }
          },
          "data": {
            "type": "object",
            "description": "Unique identifier of the account",
            "properties": {
              "locationID": {
                "type": "string",
                "description": "This defines location id",
                "example": "4a0e2Bb4Njw"
              },
              "customerLocationId": {
                "description": "This is a customer-defined location identifier in addition to the system-generated LocationId created during developer onboarding. If a `customerLocationId` is not defined, the system assigns a default `locationID`. In responses, both identifiers are returned, if a customer-defined value is not set, both fields return the same system-generated LocationID",
                "example": "4a0e2Bb4Njw",
                "type": "string"
              },
              "divisionID": {
                "type": "string",
                "description": "This defines division id",
                "example": "4a0e2Bbshdh"
              },
              "accountNumber": {
                "type": "string",
                "description": "This defines account number",
                "example": "1242"
              },
              "name": {
                "type": "string",
                "description": "This defines name of the customer",
                "example": "John"
              },
              "company": {
                "type": "string",
                "description": "This defines company name",
                "example": "PB"
              },
              "addressLine1": {
                "type": "string",
                "description": "This defines address of customer",
                "example": "203, new york"
              },
              "city": {
                "type": "string",
                "description": "This defines city",
                "example": "New York"
              },
              "state": {
                "type": "string",
                "description": "This defines state",
                "example": "NY"
              },
              "postalCode": {
                "type": "string",
                "description": "This defines postal code",
                "example": "10001"
              },
              "countryCode": {
                "type": "string",
                "description": "This defines country code",
                "example": "US"
              },
              "phone": {
                "type": "string",
                "description": "This defines phone number",
                "example": "826482849"
              },
              "isReturnAddressSame": {
                "type": "boolean",
                "description": "This defines if return address is or not",
                "example": false
              },
              "altReturnAddress": {
                "type": "object",
                "description": "If a package shipped from Location_A to Location_B needs to return to Location_C. The alternate address will be printed on the label. Use this object to specify a return address different from the fromAddress. Supported by FedEx, UPS, and Purolator. <br/> Alternate return address will be returned in the response only if it is present in the location.",
                "properties": {
                  "addressLine1": {
                    "type": "string",
                    "description": "The first line of the alternate return address, such as a street address or PO Box.",
                    "example": "27 Waterview Dr"
                  },
                  "addressLine2": {
                    "type": "string",
                    "description": "The addressLine2 contains Street address or Landmark (if any).",
                    "example": "near abc street"
                  },
                  "addressLine3": {
                    "type": "string",
                    "description": "The addressLine3 contains P.O. Box (if any) near the address.",
                    "example": "near xyz street"
                  },
                  "company": {
                    "type": "string",
                    "description": "The name of the company for the alternate return address, in case if the recipient's address is not residential. <br /> `Max length = 30`.",
                    "example": "PB"
                  },
                  "email": {
                    "type": "string",
                    "description": "The email address of the recipient. It can be person's email address or company email address (for non-residential).",
                    "example": "user@email.com"
                  },
                  "residential": {
                    "type": "boolean",
                    "description": "The specified address can be Residential or Official. In case if the address is Residential, the boolean value will be 'true', else it will take 'false'.",
                    "example": true
                  },
                  "cityTown": {
                    "type": "string",
                    "description": "The city or town for the alternate return address.",
                    "example": "Shelton"
                  },
                  "countryCode": {
                    "type": "string",
                    "description": "The two-character ISO Code of the source country from this ISO country list.  The country in which the address is located. Use ISO 3166-1 Alpha-2 standard values. For best results this should be included, especially if the country name does not appear in any of the unparsedAddressLines.",
                    "example": "US"
                  },
                  "name": {
                    "type": "string",
                    "description": "The name of the recipient or organization for the alternate return address.",
                    "example": "User Name"
                  },
                  "phone": {
                    "type": "string",
                    "description": "The phone number associated with the alternate return address.",
                    "example": "203-555-1213"
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "The postal or ZIP code for the alternate return address.",
                    "example": "06484"
                  },
                  "stateProvince": {
                    "type": "string",
                    "description": "The 2-letter state or province code for the alternate return address.",
                    "example": "CT"
                  }
                }
              }
            }
          }
        }
      },
      "GetDivisionsResponse": {
        "type": "object",
        "properties": {
          "pageInfo": {
            "type": "object",
            "description": "Pagination details",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total number records displayed",
                "example": 1
              },
              "pages": {
                "type": "number",
                "description": "Total pages",
                "example": 1
              },
              "page": {
                "type": "number",
                "description": "current page",
                "example": 10
              }
            }
          },
          "data": {
            "type": "object",
            "description": "array of divisions",
            "properties": {
              "divisionID": {
                "type": "string",
                "description": "This defines division id",
                "example": "4a0e2Bb4Njw"
              },
              "name": {
                "type": "string",
                "description": "This defines name of the division",
                "example": "UK"
              }
            }
          }
        }
      },
      "error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource."
          }
        },
        "required": [
          "message"
        ]
      },
      "Errors": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "errorCode": {
              "type": "string",
              "description": "Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g. validation-error.",
              "example": "validation_error"
            },
            "errorDescription": {
              "type": "string",
              "description": "The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)."
            },
            "additionalCode": {
              "type": "string",
              "description": "A unique identifier for the error, for example 1101055, 0100008, or 1021126."
            },
            "additionalInfo": {
              "type": "string",
              "description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceid, or if the information is missing."
            },
            "additionalParameters": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "The field(s) that might be incorrect in the request."
              }
            }
          }
        }
      },
      "NotFoundErrors": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "errorCode": {
              "type": "string",
              "example": "not_found",
              "description": "Error code(s) that appear due HTTP 404 Page or File not found."
            },
            "errorDescription": {
              "type": "string",
              "example": "resource not found",
              "description": "The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource."
            },
            "additionalCode": {
              "type": "string",
              "description": "A unique identifier for the error, for example 0100025, 1110017, or 1090001."
            },
            "additionalInfo": {
              "type": "string",
              "description": "Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`."
            },
            "additionalParameters": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "The field(s) that might be incorrect in the request."
              }
            }
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "The request could not be authorized.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "The request could not be completed due to an internal error.",
        "content": {}
      },
      "BadRequestError": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Errors"
            }
          }
        }
      },
      "NotFoundError": {
        "description": "The requested resource was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/NotFoundErrors"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}