CINXE.COM

<!DOCTYPE html><html lang="en"><head><script type="text/javascript" src="https://web-static.archive.org/_static/js/bundle-playback.js?v=7YQSqjSh" charset="utf-8"></script> <script type="text/javascript" src="https://web-static.archive.org/_static/js/wombat.js?v=txqj7nKC" charset="utf-8"></script> <script>window.RufflePlayer=window.RufflePlayer||{};window.RufflePlayer.config={"autoplay":"on","unmuteOverlay":"hidden"};</script> <script type="text/javascript" src="https://web-static.archive.org/_static/js/ruffle/ruffle.js"></script> <script type="text/javascript"> __wm.init("https://web.archive.org/web"); __wm.wombat("https://dev.bitly.com/docs/getting-started/migrating-from-v3","20220921151649","https://web.archive.org/","web","https://web-static.archive.org/_static/", "1663773409"); </script> <link rel="stylesheet" type="text/css" href="https://web-static.archive.org/_static/css/banner-styles.css?v=p7PEIJWi" /> <link rel="stylesheet" type="text/css" href="https://web-static.archive.org/_static/css/iconochive.css?v=3PDvdIFv" />  <meta charset="utf-8"/><meta name="viewport" content="width=device-width"/><link rel="shortcut icon" href="https://web.archive.org/web/20220921151649im_/https://dl6fh5ptkejqa.cloudfront.net/0482a3c938673192a591f2845b9eb275.png" type="image/x-icon"/><title>Migrating from V3 | Bitly Developer</title><meta name="next-head-count" content="4"/><link rel="preload" href="/web/20220921151649/https://dev.bitly.com/_next/static/css/864e502d90faa99e.css" as="style"/><link rel="stylesheet" href="/web/20220921151649cs_/https://dev.bitly.com/_next/static/css/864e502d90faa99e.css" data-n-g=""/><link rel="preload" href="/web/20220921151649/https://dev.bitly.com/_next/static/css/1927f8520746651a.css" as="style"/><link rel="stylesheet" href="/web/20220921151649cs_/https://dev.bitly.com/_next/static/css/1927f8520746651a.css" data-n-p=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/polyfills-c67a75d1b6f99dc8.js"></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/webpack-9b312e20a4e32339.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/framework-f5960d7d0dbb4e82.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/main-46efc285e0f364ba.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/pages/_app-7a045c60b3a601c7.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/317-1fc7d99ee6c1cb15.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/735-c05174667c1dcc3e.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/678-be054443c6232966.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/chunks/pages/docs/%5B...docs%5D-2cabd20c823c5282.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/ab5240ac6902299e99f0b1ef8ad25294f673f4a6/_buildManifest.js" defer=""></script><script src="/web/20220921151649js_/https://dev.bitly.com/_next/static/ab5240ac6902299e99f0b1ef8ad25294f673f4a6/_ssgManifest.js" defer=""></script></head><body><div id="__next"><div class="Layout_layout__WuuTt"><div class="Layout_header__HIFcZ"><header class="Header_header__jiqMu"><div class="Header_headerContent__6viXb"><div class="Header_headerIcon__fYgGU"><svg xmlns="http://www.w3.org/2000/svg" viewbox="-1376 546.6 90 45" xml:space="preserve"><title>Bitly</title><path d="M-1329.1 577c-4.5 0-7-2.7-7-6 0-1.3.1-11.4.1-11.4-1.5 0-2.2-.8-2.2-1.7 0-1 .8-1.9 2-1.9v-4.7c0-1.6 1.2-2.9 2.8-2.9 1.6 0 2.8 1.3 2.8 2.9 0 1.2-.1 2.8-.1 4.7h2.9c1.5 0 2.2.8 2.2 1.9 0 1.1-.8 1.8-1.9 1.8h-3.2c-.1 3.2-.2 7.1-.2 10.1 0 1.1.8 2.4 2.6 2.4 4.3 0 5.5-4.3 5.5-12.4 0-1.1.9-1.9 1.9-1.9 1.1 0 1.9.8 1.9 1.9.1 10.7-2.5 17.2-10.1 17.2"></path><path d="M-1310.9 560.5s1.8-1.2 2.9-1.2c1.1 0 .9.2.9 1.3 0 11.6-2.1 16.5-9.6 16.5-3.3 0-6.3-2.4-6.3-5.4 0-1.2.2-3.5.2-4.6 0-11.2-.2-13.5-.2-16.8 0-1.6 1.3-3 2.9-3 1.6 0 2.8 1.3 2.8 2.9 0 3.3-.4 8-.5 20.4 0 1 .5 1.8 1.8 1.8 4.3-.2 4.9-5.1 5.1-11.9"></path><path d="M-1297.3 575s-1.6 2.1-5.6 2c-5.3-.1-7.7-4.3-8-8.6-.2-3.3-.1-5.1-.1-7.3 0-1.6 1.1-2.9 2.6-2.9 1.6 0 2.5 1.3 2.5 2.9 0 2.1-.1 3.5-.2 5.9 0 2.8.9 5.3 3.2 5.2 2.2 0 4.7-.9 4.7-5.7v-5.4c0-1.6 1.1-2.9 2.7-2.9s2.7 1.3 2.7 2.9c0 2.1-.2 3.8-.2 7.1 0 0-.1 6.6.1 8.1.7-.2 1.8-1 2.9-2.7.7-1 2-1.3 2.7-.8 1.1.6 1.1 1.9.6 2.8-1.1 2.3-2.4 3.8-5.9 5 0 4-.3 9.8-7.6 10.9-6.3.9-9.1-2.7-9.1-5.8 0-4.9 4.9-6.3 11.9-8.1l.1-2.6zm.6 6.4c-3.6.8-8 1.9-8 4.1 0 2.1 2.2 2.4 4 2.1 3.7-.8 4.1-3 4-6.2zM-1347.6 571.6c0-1.3-.2-12.2-.2-12.2 0-1.6 1-2.9 2.6-2.9s2.6 1.4 2.6 2.9c-.2 5.1-.3 8.4-.3 10.2 0 1 .6 2.6 2.2 2.6 3.8 0 4.6-3.5 4.6-12.1 0-1.1 1.1-1.9 2.2-1.9s1.9.8 1.9 1.9c0 13-2.3 16.9-9.6 16.9-2.8 0-6-1.9-6-5.4"></path><path d="M-1345.8 557.5c-1.1 0-1.1.2-1.8 1.3 0 4.8-1.2 10.7-6.6 12.9 3.8-8-.1-15.3-6.4-15.3-3 0-4.9 1.1-6.1 2.1 0-2.3.1-6.4.1-6.4 0-2.9-1-5.1-4.5-5.2-2 0-3.5.9-4.5 3-.3.8-.2 1.6.5 2 .6.3 1.5.1 1.9-.5.3-.4.5-.5.7-.4.4 0 .4.7.5 1.2 0 .3.3 5.1.2 17.7 0 3.5 2.7 7.5 9.3 7.5 13 0 18.6-4.8 18.6-17.7-.3-1.2-.9-2.2-1.9-2.2zm-16.9 14.9c-2.5 0-4.2-.7-4.3-2.9v-2.2c.2-3.1 2.4-5.4 4.6-5.8 2.7-.5 4.5.7 4.5 4.2-.1 2.4-.8 6.6-4.8 6.7zM-1345.1 548.4c1.6 0 2.9 1.3 2.9 2.9s-1.3 2.9-2.9 2.9c-1.6 0-2.9-1.3-2.9-2.9s1.3-2.9 2.9-2.9"></path></svg>Developer</div><div class="Header_desktopHeaderLinks__afkP5"><nav><a class="Header_link__GeEkF Header_activeLink__QO_Eu" href="/web/20220921151649/https://dev.bitly.com/">Documentation</a><a class="Header_link__GeEkF" href="/web/20220921151649/https://dev.bitly.com/api-reference/">API Reference</a></nav><div class="Header_ctaWrapper__rejBO"><a class="Button_button__45M_W" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/pricing" target="_blank" rel="noopener noreferrer">Start Now</a></div></div><div class="Header_mobileHamburger__i_8mq"><div class="Header_menuIcon__5w7RR"><svg height="32" style="enable-background:new 0 0 32 32" width="32" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"><title>Navigation</title><path d="M4 10h24a2 2 0 0 0 0-4H4a2 2 0 0 0 0 4zm24 4H4a2 2 0 0 0 0 4h24a2 2 0 0 0 0-4zm0 8H4a2 2 0 0 0 0 4h24a2 2 0 0 0 0-4z"></path></svg></div></div></div></header></div><div class="Layout_body__KWn_X"><nav class="Layout_navigation__1M5jp Layout_navigationHide__DviHj"><div class="Header_mobileHeaderLinks__EmNZ6"><nav><a class="Header_link__GeEkF Header_activeLink__QO_Eu" href="/web/20220921151649/https://dev.bitly.com/">Documentation</a><a class="Header_link__GeEkF" href="/web/20220921151649/https://dev.bitly.com/api-reference/">API Reference</a></nav><div class="Header_ctaWrapper__rejBO"><a class="Button_button__45M_W" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/pricing" target="_blank" rel="noopener noreferrer">Start Now</a></div></div><div><div class="SideNavHeader_sideNavHeader__sGWeT">Getting Started</div><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/getting-started/introduction/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Introduction</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/getting-started/authentication/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Authentication</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/getting-started/rate-limits/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Rate Limits</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/getting-started/troubleshooting-tips/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Troubleshooting & Tips</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/getting-started/migrating-from-v3/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST SideNavLink_selected__khrV0">Migrating from V3</div></div></a><div class="SideNavHeader_sideNavHeader__sGWeT">Tutorials</div><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/create-a-test-account/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Create a Test Account</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/shorten-customize-links/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Shorten & Customize Links</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/retrieve-metrics/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Retrieve Metrics</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/create-a-webhook/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Create a Webhook</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/integrate-bitly-in-your-app/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Integrate Bitly in Your App</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/tutorials/generate-qr-codes/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Generate QR Codes</div></div></a><div class="SideNavHeader_sideNavHeader__sGWeT">SDKs</div><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/sdks/openapi-30/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">OpenAPI 3.0</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/sdks/android-sdk/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">Android SDK</div></div></a><a class="SideNavLink_anchor__sjeOh" href="/web/20220921151649/https://dev.bitly.com/docs/sdks/ios-sdk/"><div class="SideNavLink_sideNavLink__gSTmq"><div class="SideNavLink_content__aDTST">iOS SDK</div></div></a></div></nav><main class="Layout_content__Dwd3J"><div class="Markdown_Markdown__68s8u"><h1>Migrating from V3</h1> <p>The latest version of the Bitly API is V4. For customers migrating from V3, this documentation will highlight some of the changes that we’ve made and how to adapt your integration to work with V4.</p> <h2>Authentication</h2> <p>How you authenticate to the Bitly API has changed with V4. Previously your authentication token would be provided as the <strong>access_token</strong> query parameter on each request. V4 instead requires that the token be provided as part of the Authorization header on each request. For example: 'Authorization: Bearer {token}'</p> <p>For full details on requesting an access token via the API, please see the documentation <a href="https://web.archive.org/web/20220921151649/https://dev.bitly.com/v4/#section/Authentication" rel="noreferrer" target="_blank">here</a>.</p> <h2>Group Aware</h2> <p>With <a href="https://web.archive.org/web/20220921151649/https://support.bitly.com/hc/en-us/articles/115004396107" rel="noreferrer" target="_blank">Group Permissions</a>, Bitly links and other data elements roll up into a group. In V3 you were required to generate a different OAuth token to view each group’s data, but in V4 you can provide the group GUID as part of the request.</p> <p>If you’re not subscribed to the Enterprise plan, you only have a single group associated with your account. If you’re an Enterprise customer, you may have multiple groups associated with your account.</p> <blockquote> <p>It's important to provide the group GUID for the correct Enterprise group, otherwise you may impede your workflow by pointing to a group with lower rate limits. Users can also set their default group in Bitly. To change the default group, sign in to Bitly, open the profile menu, select <strong>Settings</strong>, click <strong>Integrations</strong>, choose the default group and click <strong>Save changes</strong>.</p> </blockquote> <p>Your groups can be retrieved via the following request:</p> <div><div class="CodeSyntaxSelector_body__hBJ7j" tabindex="0"><div class="CodeBlock_codeBlock__KlURa"><pre tabindex="0" style="color:#36383b;font-family:ProximaNova, monospace;line-height:1.2;font-size:1rem"><code style="white-space:pre"><span>GET https://api-ssl.bitly.com/v4/groups HTTP/1.1 </span>Host: api-ssl.bitly.com Authorization: Bearer {ACCESS_TOKEN} Accept: application/json </code></pre></div></div></div> <p>Some endpoints within the application, especially those dealing with Bitly links and metrics, will require a group GUID to request the data. For example, to request all the links for a group requires the following request:</p> <div><div class="CodeSyntaxSelector_body__hBJ7j" tabindex="0"><div class="CodeBlock_codeBlock__KlURa"><pre tabindex="0" style="color:#36383b;font-family:ProximaNova, monospace;line-height:1.2;font-size:1rem"><code style="white-space:pre"><span>GET https://api-ssl.bitly.com/v4/groups/GUID/bitlinks HTTP/1.1 </span>Host: api-ssl.bitly.com Authorization: Bearer ACCESS_TOKEN </code></pre></div></div></div> <p>The API also provides a default group GUID for the user. There are endpoints and an in-app setting available to set this default group GUID. To change the user's default group in-app, sign in to Bitly, open the profile menu, select <strong>Settings</strong>, click <strong>Integrations</strong>, choose the default group and click <strong>Save changes</strong>.</p> <p>The default group is used when a group GUID is not provided on shortening calls. The default group GUID is <strong>only</strong> used for shortening endpoints.</p> <blockquote> <p>Even if you are a subscriber to the Free Bitly plan, the group GUID will still be required in these requests.</p> </blockquote> <h2>RESTfulness</h2> <p>The Bitly V4 API follows the more standard REST convention of utilizing the HTTP response codes to identify the status of the response. These include, but are not limited to:</p> <ul> <li><strong>200 - SUCCESS</strong></li> <li><strong>400 - INVALID</strong></li> <li><strong>403 - FORBIDDEN</strong></li> <li><strong>404 - NOT FOUND</strong></li> <li><strong>500 - INTERNAL ERROR</strong></li> </ul> <p>In addition, V4 makes better use of the various methods for submitting data. GET requests will return data, POST requests are for creation, PATCH requests are for modification and DELETE requests are for removal.</p> <p>A major difference is how the data is delivered. Under V3 responses were contained in a data envelope and would look like this:</p> <div><div class="CodeSyntaxSelector_body__hBJ7j" tabindex="0"><div class="CodeBlock_codeBlock__KlURa"><pre tabindex="0" style="color:#36383b;font-family:ProximaNova, monospace;line-height:1.2;font-size:1rem"><code style="white-space:pre"><span>{ </span> “status_code”: 200,  “status_text”: “SUCCESS”,  “data”: {  //response data object  } } </code></pre></div></div></div> <p>V4 instead returns a JSON object containing all the data provided by the response. For example a standard Bitly link response is structured like this:</p> <div><div class="CodeSyntaxSelector_body__hBJ7j" tabindex="0"><div class="CodeBlock_codeBlock__KlURa"><pre tabindex="0" style="color:#36383b;font-family:ProximaNova, monospace;line-height:1.2;font-size:1rem"><code style="white-space:pre"><span>{ </span> "references": {  "property1": "string",  "property2": "string"  },  "archived": true,  "tags": [  "string"  ],  "created_at": "string",  "title": "string",  "deeplinks": [  {  "bitlink": "string",  "install_url": "string",  "created": "string",  "app_uri_path": "string",  "modified": "string",  "install_type": "string",  "app_guid": "string",  "guid": "string",  "os": "string"  }  ],  "created_by": "string",  "long_url": "string",  "custom_bitlinks": [  "string"  ],  "link": "string",  "id": "string" } </code></pre></div></div></div> <p>V4 has also simplified how much data is returned on an individual request. Because of the nested nature of some of our data and to improve the overall performance of the API we include a collection of <strong>references</strong> which provide request URLs for returning additional data. For example, here is the <strong>references</strong> collection for a Bitlink:</p> <div><div class="CodeSyntaxSelector_body__hBJ7j" tabindex="0"><div class="CodeBlock_codeBlock__KlURa"><pre tabindex="0" style="color:#36383b;font-family:ProximaNova, monospace;line-height:1.2;font-size:1rem"><code style="white-space:pre"><span>"references":{ </span> "group":"https://api-ssl.bitly.com/v4/groups/GUID" } </code></pre></div></div></div> <p>Instead of nesting the full Group object and any additional objects it may reference, this request URL is provided to retrieve that additional data if required.</p></div><footer><div class="Footer_footer__7PvU2"><div class="Footer_row__1ruA0"><div class="Footer_title__Ct_v_">Resources</div><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/https://bitly.com/blog/" class="Footer_link__V8hyW">Blog</a><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/resources/" class="Footer_link__V8hyW">Webinar and Ebooks</a></div><div class="Footer_row__1ruA0"><div class="Footer_title__Ct_v_">Legal</div><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/privacy/" class="Footer_link__V8hyW">Privacy Policy</a><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/terms-of-service/" class="Footer_link__V8hyW">Terms of Service</a></div><div class="Footer_row__1ruA0"><div class="Footer_title__Ct_v_">Company</div><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/https://bitly.com/pages/careers/" class="Footer_link__V8hyW">Careers</a><a target="_blank" rel="noopener noreferrer" href="https://web.archive.org/web/20220921151649/mailto:api@bit.ly" class="Footer_link__V8hyW">Contact</a></div><div class="Footer_row__1ruA0"><svg xmlns="http://www.w3.org/2000/svg" viewbox="-1376 546.6 90 45" xml:space="preserve"><title>Bitly</title><path d="M-1329.1 577c-4.5 0-7-2.7-7-6 0-1.3.1-11.4.1-11.4-1.5 0-2.2-.8-2.2-1.7 0-1 .8-1.9 2-1.9v-4.7c0-1.6 1.2-2.9 2.8-2.9 1.6 0 2.8 1.3 2.8 2.9 0 1.2-.1 2.8-.1 4.7h2.9c1.5 0 2.2.8 2.2 1.9 0 1.1-.8 1.8-1.9 1.8h-3.2c-.1 3.2-.2 7.1-.2 10.1 0 1.1.8 2.4 2.6 2.4 4.3 0 5.5-4.3 5.5-12.4 0-1.1.9-1.9 1.9-1.9 1.1 0 1.9.8 1.9 1.9.1 10.7-2.5 17.2-10.1 17.2"></path><path d="M-1310.9 560.5s1.8-1.2 2.9-1.2c1.1 0 .9.2.9 1.3 0 11.6-2.1 16.5-9.6 16.5-3.3 0-6.3-2.4-6.3-5.4 0-1.2.2-3.5.2-4.6 0-11.2-.2-13.5-.2-16.8 0-1.6 1.3-3 2.9-3 1.6 0 2.8 1.3 2.8 2.9 0 3.3-.4 8-.5 20.4 0 1 .5 1.8 1.8 1.8 4.3-.2 4.9-5.1 5.1-11.9"></path><path d="M-1297.3 575s-1.6 2.1-5.6 2c-5.3-.1-7.7-4.3-8-8.6-.2-3.3-.1-5.1-.1-7.3 0-1.6 1.1-2.9 2.6-2.9 1.6 0 2.5 1.3 2.5 2.9 0 2.1-.1 3.5-.2 5.9 0 2.8.9 5.3 3.2 5.2 2.2 0 4.7-.9 4.7-5.7v-5.4c0-1.6 1.1-2.9 2.7-2.9s2.7 1.3 2.7 2.9c0 2.1-.2 3.8-.2 7.1 0 0-.1 6.6.1 8.1.7-.2 1.8-1 2.9-2.7.7-1 2-1.3 2.7-.8 1.1.6 1.1 1.9.6 2.8-1.1 2.3-2.4 3.8-5.9 5 0 4-.3 9.8-7.6 10.9-6.3.9-9.1-2.7-9.1-5.8 0-4.9 4.9-6.3 11.9-8.1l.1-2.6zm.6 6.4c-3.6.8-8 1.9-8 4.1 0 2.1 2.2 2.4 4 2.1 3.7-.8 4.1-3 4-6.2zM-1347.6 571.6c0-1.3-.2-12.2-.2-12.2 0-1.6 1-2.9 2.6-2.9s2.6 1.4 2.6 2.9c-.2 5.1-.3 8.4-.3 10.2 0 1 .6 2.6 2.2 2.6 3.8 0 4.6-3.5 4.6-12.1 0-1.1 1.1-1.9 2.2-1.9s1.9.8 1.9 1.9c0 13-2.3 16.9-9.6 16.9-2.8 0-6-1.9-6-5.4"></path><path d="M-1345.8 557.5c-1.1 0-1.1.2-1.8 1.3 0 4.8-1.2 10.7-6.6 12.9 3.8-8-.1-15.3-6.4-15.3-3 0-4.9 1.1-6.1 2.1 0-2.3.1-6.4.1-6.4 0-2.9-1-5.1-4.5-5.2-2 0-3.5.9-4.5 3-.3.8-.2 1.6.5 2 .6.3 1.5.1 1.9-.5.3-.4.5-.5.7-.4.4 0 .4.7.5 1.2 0 .3.3 5.1.2 17.7 0 3.5 2.7 7.5 9.3 7.5 13 0 18.6-4.8 18.6-17.7-.3-1.2-.9-2.2-1.9-2.2zm-16.9 14.9c-2.5 0-4.2-.7-4.3-2.9v-2.2c.2-3.1 2.4-5.4 4.6-5.8 2.7-.5 4.5.7 4.5 4.2-.1 2.4-.8 6.6-4.8 6.7zM-1345.1 548.4c1.6 0 2.9 1.3 2.9 2.9s-1.3 2.9-2.9 2.9c-1.6 0-2.9-1.3-2.9-2.9s1.3-2.9 2.9-2.9"></path></svg><div class="Footer_description__eC8la">© 2022 Bitly</div><div class="Footer_description__eC8la">Handmade in NYC, San Francisco, Denver, and all over the world.</div><div class="Footer_socialIcons__dFxBT"><a href="https://web.archive.org/web/20220921151649/https://twitter.com/bitly" target="_blank" rel="noopener noreferrer"><svg width="24" height="20" xmlns="http://www.w3.org/2000/svg"><title>Twitter</title><path d="M23.953 2.382c-.885.399-1.83.67-2.825.794A5.063 5.063 0 0 0 23.291.384a10.01 10.01 0 0 1-3.127 1.214A4.844 4.844 0 0 0 16.574 0c-2.718 0-4.92 2.259-4.92 5.041 0 .4.045.785.127 1.153C7.69 5.996 4.066 3.982 1.64.938a5.04 5.04 0 0 0-.666 2.538 5.08 5.08 0 0 0 2.188 4.2 4.812 4.812 0 0 1-2.228-.632v.062c0 2.445 1.693 4.485 3.946 4.95a4.88 4.88 0 0 1-2.212.086c.63 2.003 2.445 3.463 4.604 3.504A9.714 9.714 0 0 1 0 17.736 13.745 13.745 0 0 0 7.557 20c9.053 0 13.998-7.685 13.998-14.34 0-.214 0-.43-.015-.645.961-.707 1.8-1.6 2.46-2.613l-.047-.02Z" fill="#121314"></path></svg></a><a href="https://web.archive.org/web/20220921151649/https://www.instagram.com/bitly/" target="_blank" rel="noopener noreferrer"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg"><title>Instagram</title><path d="M12 0C8.74 0 8.333.015 7.053.072 5.775.132 4.905.333 4.14.63a5.876 5.876 0 0 0-2.126 1.384A5.855 5.855 0 0 0 .63 4.14C.333 4.905.131 5.775.072 7.053.012 8.333 0 8.74 0 12s.015 3.667.072 4.947c.06 1.277.261 2.148.558 2.913a5.885 5.885 0 0 0 1.384 2.126A5.868 5.868 0 0 0 4.14 23.37c.766.296 1.636.499 2.913.558C8.333 23.988 8.74 24 12 24s3.667-.015 4.947-.072c1.277-.06 2.148-.262 2.913-.558a5.898 5.898 0 0 0 2.126-1.384 5.86 5.86 0 0 0 1.384-2.126c.296-.765.499-1.636.558-2.913.06-1.28.072-1.687.072-4.947s-.015-3.667-.072-4.947c-.06-1.277-.262-2.149-.558-2.913a5.89 5.89 0 0 0-1.384-2.126A5.847 5.847 0 0 0 19.86.63c-.765-.297-1.636-.499-2.913-.558C15.667.012 15.26 0 12 0Zm0 2.16c3.203 0 3.585.016 4.85.071 1.17.055 1.805.249 2.227.415.562.217.96.477 1.382.896.419.42.679.819.896 1.381.164.422.36 1.057.413 2.227.057 1.266.07 1.646.07 4.85 0 3.204-.015 3.585-.074 4.85-.061 1.17-.256 1.805-.421 2.227a3.81 3.81 0 0 1-.899 1.382 3.744 3.744 0 0 1-1.38.896c-.42.164-1.065.36-2.235.413-1.274.057-1.649.07-4.859.07-3.211 0-3.586-.015-4.859-.074-1.171-.061-1.816-.256-2.236-.421a3.716 3.716 0 0 1-1.379-.899 3.644 3.644 0 0 1-.9-1.38c-.165-.42-.359-1.065-.42-2.235-.045-1.26-.061-1.649-.061-4.844 0-3.196.016-3.586.061-4.861.061-1.17.255-1.814.42-2.234.21-.57.479-.96.9-1.381.419-.419.81-.689 1.379-.898.42-.166 1.051-.361 2.221-.421 1.275-.045 1.65-.06 4.859-.06l.045.03Zm0 3.678a6.162 6.162 0 1 0 0 12.324 6.162 6.162 0 1 0 0-12.324ZM12 16c-2.21 0-4-1.79-4-4s1.79-4 4-4 4 1.79 4 4-1.79 4-4 4Zm7.846-10.405a1.441 1.441 0 0 1-2.88 0 1.44 1.44 0 0 1 2.88 0Z" fill="#121314"></path></svg></a><a href="https://web.archive.org/web/20220921151649/https://www.linkedin.com/company/552285/admin/" target="_blank" rel="noopener noreferrer"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg"><title>LinkedIn</title><path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286h-.001ZM5.337 7.433a2.062 2.062 0 0 1-2.063-2.065 2.064 2.064 0 1 1 2.063 2.065Zm1.782 13.019H3.555V9h3.564v11.452ZM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003Z" fill="#121314"></path></svg></a><a href="https://web.archive.org/web/20220921151649/https://www.facebook.com/bitly" target="_blank" rel="noopener noreferrer"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg"><title>Facebook</title><path d="M22.676 0H1.324C.593 0 0 .593 0 1.324v21.352C0 23.408.593 24 1.324 24h11.494v-9.294H9.689v-3.621h3.129V8.41c0-3.099 1.894-4.785 4.659-4.785 1.325 0 2.464.097 2.796.141v3.24h-1.921c-1.5 0-1.792.721-1.792 1.771v2.311h3.584l-.465 3.63H16.56V24h6.115c.733 0 1.325-.592 1.325-1.324V1.324C24 .593 23.408 0 22.676 0" fill="#121314"></path></svg></a></div></div></div></footer></main></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"markdownNav":[{"type":"header","route":"/docs/getting-started","path":"/docs/01_Getting_Started","name":"Getting Started","children":[{"type":"file","route":"/docs/getting-started/introduction","path":"/docs/01_Getting_Started/001_Introduction.md","name":"Introduction","children":null},{"type":"file","route":"/docs/getting-started/authentication","path":"/docs/01_Getting_Started/002_Authentication.md","name":"Authentication","children":null},{"type":"file","route":"/docs/getting-started/rate-limits","path":"/docs/01_Getting_Started/003_Rate_Limits.md","name":"Rate Limits","children":null},{"type":"file","route":"/docs/getting-started/troubleshooting-tips","path":"/docs/01_Getting_Started/004_Troubleshooting_\u0026_Tips.md","name":"Troubleshooting \u0026 Tips","children":null},{"type":"file","route":"/docs/getting-started/migrating-from-v3","path":"/docs/01_Getting_Started/005_Migrating_from_V3.md","name":"Migrating from V3","children":null}]},{"type":"header","route":"/docs/tutorials","path":"/docs/02_Tutorials","name":"Tutorials","children":[{"type":"file","route":"/docs/tutorials/create-a-test-account","path":"/docs/02_Tutorials/001_Create_a_Test_Account.md","name":"Create a Test Account","children":null},{"type":"file","route":"/docs/tutorials/shorten-customize-links","path":"/docs/02_Tutorials/002_Shorten_\u0026_Customize_Links.md","name":"Shorten \u0026 Customize Links","children":null},{"type":"file","route":"/docs/tutorials/retrieve-metrics","path":"/docs/02_Tutorials/003_Retrieve_Metrics.md","name":"Retrieve Metrics","children":null},{"type":"file","route":"/docs/tutorials/create-a-webhook","path":"/docs/02_Tutorials/004_Create_a_Webhook.md","name":"Create a Webhook","children":null},{"type":"file","route":"/docs/tutorials/integrate-bitly-in-your-app","path":"/docs/02_Tutorials/005_Integrate_Bitly_in_Your_App.md","name":"Integrate Bitly in Your App","children":null},{"type":"file","route":"/docs/tutorials/generate-qr-codes","path":"/docs/02_Tutorials/006_Generate_QR_Codes.md","name":"Generate QR Codes","children":null}]},{"type":"header","route":"/docs/sdks","path":"/docs/03_SDKs","name":"SDKs","children":[{"type":"file","route":"/docs/sdks/openapi-30","path":"/docs/03_SDKs/001_OpenAPI_3.0.md","name":"OpenAPI 3.0","children":null},{"type":"file","route":"/docs/sdks/android-sdk","path":"/docs/03_SDKs/002_Android_SDK.md","name":"Android SDK","children":null},{"type":"file","route":"/docs/sdks/ios-sdk","path":"/docs/03_SDKs/003_iOS_SDK.md","name":"iOS SDK","children":null}]}],"markdownSource":"# Migrating from V3\n\nThe latest version of the Bitly API is V4. For customers migrating from V3, this documentation will highlight some of the changes that we’ve made and how to adapt your integration to work with V4.\n\n\n## Authentication\n\nHow you authenticate to the Bitly API has changed with V4. Previously your authentication token would be provided as the **access_token** query parameter on each request. V4 instead requires that the token be provided as part of the Authorization header on each request. For example: 'Authorization: Bearer {token}'\n\nFor full details on requesting an access token via the API, please see the documentation [here](https://dev.bitly.com/v4/#section/Authentication).\n\n\n## Group Aware\n\nWith [Group Permissions](https://support.bitly.com/hc/en-us/articles/115004396107), Bitly links and other data elements roll up into a group. In V3 you were required to generate a different OAuth token to view each group’s data, but in V4 you can provide the group GUID as part of the request.\n\nIf you’re not subscribed to the Enterprise plan, you only have a single group associated with your account. If you’re an Enterprise customer, you may have multiple groups associated with your account.\n\n\u003e It's important to provide the group GUID for the correct Enterprise group, otherwise you may impede your workflow by pointing to a group with lower rate limits. Users can also set their default group in Bitly. To change the default group, sign in to Bitly, open the profile menu, select **Settings**, click **Integrations**, choose the default group and click **Save changes**.\n\nYour groups can be retrieved via the following request:\n\n```\nGET https://api-ssl.bitly.com/v4/groups HTTP/1.1\nHost: api-ssl.bitly.com\nAuthorization: Bearer {ACCESS_TOKEN}\nAccept: application/json\n```\n\nSome endpoints within the application, especially those dealing with Bitly links and metrics, will require a group GUID to request the data. For example, to request all the links for a group requires the following request:\n\n```\nGET https://api-ssl.bitly.com/v4/groups/GUID/bitlinks HTTP/1.1\nHost: api-ssl.bitly.com\nAuthorization: Bearer ACCESS_TOKEN\n```\n\nThe API also provides a default group GUID for the user. There are endpoints and an in-app setting available to set this default group GUID. To change the user's default group in-app, sign in to Bitly, open the profile menu, select **Settings**, click **Integrations**, choose the default group and click **Save changes**.\n\nThe default group is used when a group GUID is not provided on shortening calls. The default group GUID is **only** used for shortening endpoints.\n\n\u003e Even if you are a subscriber to the Free Bitly plan, the group GUID will still be required in these requests.\n\n\n## RESTfulness\n\nThe Bitly V4 API follows the more standard REST convention of utilizing the HTTP response codes to identify the status of the response. These include, but are not limited to:\n\n* **200 - SUCCESS**\n* **400 - INVALID**\n* **403 - FORBIDDEN**\n* **404 - NOT FOUND**\n* **500 - INTERNAL ERROR**\n\nIn addition, V4 makes better use of the various methods for submitting data. GET requests will return data, POST requests are for creation, PATCH requests are for modification and DELETE requests are for removal.\n\nA major difference is how the data is delivered. Under V3 responses were contained in a data envelope and would look like this:\n\n```\n{\n “status_code”: 200,\n “status_text”: “SUCCESS”,\n “data”: {\n //response data object\n }\n}\n```\n\nV4 instead returns a JSON object containing all the data provided by the response. For example a standard Bitly link response is structured like this:\n\n```\n{\n \"references\": {\n \"property1\": \"string\",\n \"property2\": \"string\"\n },\n \"archived\": true,\n \"tags\": [\n \"string\"\n ],\n \"created_at\": \"string\",\n \"title\": \"string\",\n \"deeplinks\": [\n {\n \"bitlink\": \"string\",\n \"install_url\": \"string\",\n \"created\": \"string\",\n \"app_uri_path\": \"string\",\n \"modified\": \"string\",\n \"install_type\": \"string\",\n \"app_guid\": \"string\",\n \"guid\": \"string\",\n \"os\": \"string\"\n }\n ],\n \"created_by\": \"string\",\n \"long_url\": \"string\",\n \"custom_bitlinks\": [\n \"string\"\n ],\n \"link\": \"string\",\n \"id\": \"string\"\n}\n```\n\nV4 has also simplified how much data is returned on an individual request. Because of the nested nature of some of our data and to improve the overall performance of the API we include a collection of **references** which provide request URLs for returning additional data. For example, here is the **references** collection for a Bitlink:\n\n```\n\"references\":{\n \"group\":\"https://api-ssl.bitly.com/v4/groups/GUID\"\n}\n```\n\nInstead of nesting the full Group object and any additional objects it may reference, this request URL is provided to retrieve that additional data if required.\n"},"__N_SSG":true},"page":"/docs/[...docs]","query":{"docs":["getting-started","migrating-from-v3"]},"buildId":"ab5240ac6902299e99f0b1ef8ad25294f673f4a6","isFallback":false,"gsp":true,"scriptLoader":[]}</script></body></html>